Importation du catalogue

Créer et mettre à jour un catalogue des objets en utilisant l'importation JSON

Vous pouvez créer, mettre à jour ou désactiver des objets en utilisant l’importation à partir d’un fichier JSON.

Note
Vous pouvez créer, mettre à jour ou désactiver des objets en utilisant des appels API ou manuellement dans le Compte éditeur. Toutefois, ces deux approches impliquent une demande ou une action distincte pour chaque objet. Avec l’importation, en revanche, vous pouvez accomplir ces actions pour plusieurs objets simultanément en les spécifiant dans un seul fichier JSON.

Cet outil vous permet :

Fonctionnalités :

  • Prise en charge des types de biens suivants :
    • objets virtuels ;
    • monnaie virtuelle ;
    • packages de monnaie virtuelle ;
    • lots.
  • Validation des données. Si la structure du fichier ou le format des données ne répond pas aux exigences, une liste d’erreurs s’affiche lors de l’importation.

Limites :

Note
Pour les objets pré-créés, vous pouvez importer des prix régionaux à partir d’un fichier CSV.

Importation du catalogue des objets

Pour importer un catalogue des objets à partir d’un fichier :

  1. Ouvrez le projet dans le Compte éditeur.
  2. Dans le menu latéral, cliquez sur Store et accédez à la section Virtual currency, Virtual items ou Bundles.
  3. Cliquez sur Import items.

  1. Choisissez l'action :
    • Add new items — seuls les objets avec de nouvelles UGS seront ajoutés ;
    • Add new items and update existing ones — les objets avec de nouvelles UGS seront ajoutés et les données des objets existants seront mises à jour ;
    • Add new, update existing, disable missing items — les objets avec des UGS provenant du fichier seront ajoutés/mis à jour. S'il existe un objet dans le catalogue, mais qu'il n'y a pas d'UGS correspondante dans le fichier, le statut de l'objet dans le Compte éditeur sera changé en Partially available — l'objet ne peut pas être acheté séparément, mais est disponible dans le cadre d'un lot ou d'un bonus.

  1. Remplissez le fichier pour l'importation :
    • Téléchargez le modèle de fichier dans la fenêtre de téléchargement et remplissez-le selon l'exemple ci-dessous ;
    • Exportez les objets et utilisez le fichier exporté comme modèle ;
    • Créez votre propre fichier JSON et remplissez-le selon l'exemple ci-dessous.

Exemple de fichier JSON complet :

Copy
Full screen
Small screen

{
    "virtual_currency": [
        {
            "sku": "Gem_test_import",
            "name": {
                "en": "Gem_test_import"
            },
            "type": "virtual_currency",
            "description": {
                "en": "my test imported currency"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
            "description": {
                "en": "my test imported currency",
                "de": "meine importierte Testwährung"
            },
            "attributes": [],
            "is_free": false,
            "order": 1,
            "groups": [],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 2,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "media_list": [],
            "vc_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "inventory_options": {
                "consumable": true,
                "expiration_period": null
            },
            "is_hard": false
        }
    ],
    "virtual_items": [
        {
            "sku": "event_access_test_import",
            "name": {
                "en": "Special Event Access_test_import"
            },
            "type": "virtual_good",
            "description": {
                "en": "Get special event access as a bonus only on your first purchase. Find the right doggy at the Robo-Dog Exhibition!"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/images/1e3ef1a96cc9dd8d98bc124d5d6fad79.png",
            "long_description": null,
            "attributes": [],
            "is_free": false,
            "order": 1,
            "groups": [
                "my_test_group"
            ],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 35,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "media_list": [],
            "vc_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "inventory_options": {
                "consumable": true,
                "expiration_period": null
            }
        }
    ],
    "virtual_currency_packages": [
        {
            "item_id": 441982,
            "sku": "small_gold_pack_test_import",
            "type": "bundle",
            "name": {
                "en": "Small gold pack"
            },
            "bundle_type": "virtual_currency_package",
            "description": {
                "en": "Gold x100"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/images/ba43c46ea75fd5713c210f5736993a92.png",
            "vc_prices": [],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 5,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "attributes": [],
            "long_description": null,
            "media_list": [],
            "order": 100000000,
            "is_free": false,
            "groups": [],
            "content": [
                {
                    "sku": "Gem_test_import",
                    "quantity": 100
                }
            ]
        }
    ],
    "bundles": [
        {
            "item_id": 684024,
            "sku": "start_pack_test_import_test_import",
            "type": "bundle",
            "name": {
                "en": "Legendary Start Pack"
            },
            "bundle_type": "standard",
            "description": {
                "en": "Crystal x 1\nGem x 1"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
            "regional_prices": [],
            "prices": [
                {
                    "amount": 20,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "virtual_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "attributes": [],
            "long_description": null,
            "media_list": [],
            "order": 5,
            "is_free": false,
            "groups": [
                "my_test_group"
            ],
            "content": [
                {
                    "sku": "Gem_test_import",
                    "quantity": 1
                },
                {
                    "sku": "event_access_test_import",
                    "quantity": 1
                }
            ]
        }
    ]
}

  1. Téléchargez le fichier dans le champ correspondant de la fenêtre d’importation.
  2. En cas d’erreurs lors de l’importation, une liste de celles-ci avec les recommandations de correction s'affiche dans la fenêtre d'importation. Apportez les modifications nécessaires au fichier et téléchargez-le à nouveau.

Après le téléchargement réussi, les objets avec les UGS spécifiées seront créés, mis à jour ou désactivés.

Note
Vous pouvez importer des objets à l’aide de l’appel API Importer des objets via un fichier JSON.
Veillez à suivre les recommandations ci-dessus pour remplir correctement le fichier et éviter toute erreur lors de l’importation.

Exportation du catalogue des objets

Pour exporter un objet ou un catalogue des objets vers un fichier JSON :

  1. Ouvrez le projet dans le Compte éditeur.
  2. Dans le menu latéral, cliquez sur Store et accédez à la section Virtual currency, Virtual items ou Bundles.
  3. Cliquez sur Export items.

  1. Choisissez l'action :
    • Export all items — le catalogue complet de tous les types de biens de ce projet sera exporté. Par exemple, si vous accédez à la section Virtual Currency et exportez tous les objets, le fichier JSON déchargera les monnaies virtuelles, les packages de monnaie virtuelle, les objets virtuels et les packages de clés de jeu de votre projet ;
    • Export only selected items — dans la fenêtre qui s'affiche, sélectionnez les objets à exporter.

  1. Cliquez sur Export.

Le téléchargement du fichier JSON démarre automatiquement.

Importer un catalogue depuis des plateformes externes

Importez des objets et des abonnements depuis des plateformes externes et synchronisez l’inventaire utilisateur.

Avis
Après l’importation, pour synchroniser les modifications apportées au catalogue des objets et des abonnements dans la source d’importation et côté Xsolla, procédez de l’une des manières suivantes :Si le catalogue ne peut pas être importé, configurez le catalogue des objets et des abonnements dans le Compte éditeur ou via les méthodes API.

Importer un catalogue depuis Google Play

Avis

Avant de commencer l’importation, vérifiez que Google Play Android Developer API est activée dans votre projet Google Play. Pour ce faire, accédez à https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project={project_id}, où project_id correspond à l’ID de votre projet dans Google Play. Si cette API est désactivée, activez-la. Notez que les paramètres prennent un certain temps à s’appliquer, donc l’importation peut échouer si vous essayez immédiatement après avoir activé les paramètres. Attendez quelques minutes et réessayez.

  1. Ouvrez le projet dans votre Compte éditeur.
  2. Cliquez sur Store dans le menu latéral.
  3. Dans le volet Catalog Management, cliquez sur Configure.
  4. Dans le volet Integration with external platforms, cliquez sur Configure.
  5. Dans le volet Google Play, cliquez sur Configure.
  6. Spécifiez Application ID, c'est-à-dire l'identifiant de votre application sur Google Play.
Note
Vous pouvez trouver l’ID de l’application sur Google Play Console. Dans le menu latéral, cliquez sur All apps. Trouvez l’application dont vous avez besoin dans le tableau. Son ID sera spécifié dans la colonne App, à côté du nom et du logo.
  1. Téléchargez un fichier JSON avec la clé privée.
Note
La clé privée est générée lorsque vous créez votre compte de service.

  1. Accédez à Google Play Console, dans le menu latéral, cliquez sur Users and permissions et ajoutez un compte de service en tant que nouvel utilisateur avec le rôle Android Management User. Pour ce faire, vous devez avoir le rôle de Project IAM admin.

  1. Cliquez sur Save.
  2. Cliquez sur Start import. L'importation du catalogue démarre automatiquement.
Note
SKU correspond à l’identifiant du produit dans la source d’importation.
  1. Pour vendre des objets virtuels dans le magasin en ligne créé par Site Builder, configurez les groupes d'objets dans le Compte éditeur et attribuez-en un ou plusieurs à chaque objet.
  2. Pour afficher les images des objets, téléchargez-les vers votre Compte éditeur.
Note
Pour les utilisateurs du Bangladesh, les prix du catalogue seront affichés dans la devise par défaut (USD), plutôt qu’en BDT.

Importer un catalogue depuis App Store

Note
Seuls les produits ayant le statut Approved dans App Store Connect seront importés. Dans la section Store du Compte éditeur, les objets importés apparaîtront avec le statut Partially Available. Pour les rendre visibles, changez leur statut en Available.
Avant d’importer un catalogue depuis l’App Store, assurez-vous d’obtenir les informations suivantes :

Obtenir l'ID de l'application

Pour obtenir votre ID d’application dans App Store Connect :
  1. Connectez-vous à App Store Connect.
  2. Accédez à la section Apps.

  3. Ouvrez la page de votre application.
  4. Naviguez vers General Information > App Information.
  5. Dans General Information, copiez l’ID d’application dans le champ Apple ID.

Obtenir la clé API et l'Issuer ID

L’Issuer ID dans App Store Connect sert à interagir avec Apple API, y compris App Store Connect API. Il est indispensable pour configurer les clés API et automatiser des tâches comme la gestion des applications, la récupération des données analytiques et d’autres opérations sur App Store Connect.

La clé API est un identifiant unique utilisé pour authentifier les requêtes API dans App Store Connect API et garantir un accès sécurisé aux données et fonctionnalités du compte Apple Developer.

Pour obtenir l’Issuer ID et la clé API dans App Store Connect :

  1. Connectez-vous à App Store Connect et accédez à la section Users and Access.
  2. Ouvrez l’onglet Integrations.
  3. Dans le menu latéral Keys, cliquez sur App Store Connect API.
  4. Accédez à l’onglet Team Keys. Cliquez sur l’icône + pour créer une nouvelle clé API.

  5. Dans la fenêtre Generate API Key, attribuez un nom à la clé et définissez son niveau d’accès.
  6. Cliquez sur Generate.

  7. La clé nouvellement créée apparaîtra dans la liste des clés API actives. Téléchargez-la en tant que fichier P8 et copiez le Key ID.

  8. Dans l’onglet Team Keys, copiez l’Issuer ID.

Importer un catalogue depuis l'App Store

  1. Ouvrez le Compte éditeur et accédez à Store > Catalog management > Integration with external platforms > App Store.
  2. Fournissez les données obtenues dans App Store Connect :
    • ID d’application ;
    • Fichier de clé privée (P8) ;
    • Issuer ID ;
    • Key ID.
  3. Cliquez sur Démarrer l’importation. L’importation du catalogue commence automatiquement.

Pour vendre des objets virtuels dans le magasin en ligne créé à l’aide de Site Builder, créez des groupes d’objets dans le Compte éditeur et assignez un ou plusieurs groupes à chaque objet virtuel.

Pour afficher les images des objets, téléchargez-les et modifiez l’objet importé dans Store > Virtual Items.

Note
L’UGS d’un produit correspond à l’ID du produit dans la source d’importation.

Importer un catalogue depuis PlayFab

Avis
Version de l’API PlayFab prise en charge : Economy v1.
Le guide pour importer un catalogue depuis PlayFab est fourni dans la documentation.

Réimporter le catalogue

Lors de la réimportation du catalogue, vous devez prendre en compte les points suivants :

  • les objets déjà présents dans Store seront mis à jour ;
  • les objets qui ne sont pas disponibles dans Store seront ajoutés ;
  • les objets qui ont été supprimés de la source d’importation resteront dans Store. Vous pouvez les supprimer dans votre Compte éditeur ou via API.

Création automatique des biens via API

Pour créer de nombreux objets sur la base de données de votre système, vous pouvez utiliser l’automatisation à l’aide de l’API.

Vous devez :

Si vous souhaitez utiliser des groupes d’objets, créez-les à l’avance via l’interface du Compte éditeur.

Si vous souhaitez utiliser plusieurs types d’objets, créez-les dans l’ordre suivant :

  1. Groupes d’objets dans le Compte éditeur.
  2. Monnaies virtuelles.
  3. Objets virtuels.
  4. Packages de monnaie virtuelle.
  5. Lots.

Voici un exemple de script qui appelle de manière répétée la méthode Créer un objet virtuel pour créer des objets virtuels.

Le script est développé en utilisant JavaScript et le moteur d’exécution JavaScript — Node.js.

  1. Importez la fonction fetch du module “node-fetch” pour envoyer des requêtes HTTP au serveur Xsolla.
Copy
Full screen
Small screen
import fetch from "node-fetch";
  1. Définissez les constantes nécessaires à l’autorisation de la requête. Au lieu de <your project_id from PA> et <your api key from PA>, insérez vos valeurs pour l’ID de projet et la clé API, qui seront encodées en Base64 pour une utilisation ultérieure dans les requêtes API.
Copy
Full screen
Small screen
const projectId = <your project_id from PA>;

const apiKey = <your api key from PA>;

const buff = new Buffer(`${projectId}:${apiKey}`);

const basicAuth = buff.toString('base64')
  1. Implémentez la fonction d’aide sleep, qui est utilisée pour créer un délai lors de l’envoi de requêtes. Cela est nécessaire afin de ne pas dépasser les limites de taux des requêtes API.
Copy
Full screen
Small screen
function sleep(ms) {

   return new Promise(resolve => setTimeout(resolve, ms));

}
  1. Implémentez la fonction getItems, spécifique à votre système, pour récupérer les données des objets depuis votre système.
Copy
Full screen
Small screen
async function getItems() {

   // receive items from the original system or read from a pre-prepared file

   return items;

}
  1. Implémentez la fonction prepareData, spécifique à votre système, pour formater les données des objets conformément au format de données dans l’appel API Créer un objet virtuel.
Copy
Full screen
Small screen
function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}
  1. Ajoutez la fonction createItem, qui envoie une requête POST à l’API Xsolla pour créer un objet virtuel.
Copy
Full screen
Small screen
async function createItem(item) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;



   return await fetch(url, {

       method: "POST",

       headers: {

           Authorization: "Basic " + basicAuth,

           "Content-Type": "application/json"

       },

       body: JSON.stringify(item),

   });

}
  1. Ajoutez la fonction checkItemExist, qui vérifie l’existence d’un objet virtuel avec une UGS spécifique. Cette fonction envoie une requête GET à l’API Xsolla :
    • Si la réponse retourne un code HTTP 404, l’objet avec l’UGS spécifiée n’est pas trouvé et doit être créé ;
    • Si la réponse retourne un code HTTP 200, l’objet avec l’UGS spécifiée est trouvé et n’a pas besoin d’être créé.
Copy
Full screen
Small screen
async function checkItemExist(sku) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;

   const response = await fetch(url, {

       method: "GET",

       headers: {

           Authorization: "Basic " + basicAuth

       }

   });

   return response.status !== 404;

}
  1. Ajoutez la fonction createItems, qui parcourt la liste des objets et vérifie l’existence du côté de Xsolla d’un objet avec une UGS de votre système. Si aucun objet avec une telle UGS n’est trouvé, la fonction le crée. Les informations de progression s’affichent dans la console.
Copy
Full screen
Small screen
async function createItems(items) {

   let success = 0;

   let alreadyCreated = 0;

   for (let i = 0; i < items.length; i++) {

       const item = items[i];

       if (item['sku'] === undefined) {

           console.log(`${i} Field "sku" not specified`);

           continue;

       }

       const sku = item['sku'];

       if (await checkItemExist(sku)) {

           console.log(`${i} Item with sku "${sku}" already created`);

           alreadyCreated++;

           continue;

       }

       const response = await createItem(item);

       if (response.status === 201) {

           console.log(`${i} Item with sku "${sku}" successfully created`)

           success++;

       } else {

           const jsonData = await response.json();

           console.log(`${i} An error occurred while creating the items with sku "${sku}"`);

           console.log(jsonData);

       }

       // add a delay so as not to run into rate limits

       await sleep(500);

   }

   console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);

}
  1. Ajouter la fonction run qui appelle toutes les fonctions ci-dessus dans le bon ordre.
Copy
Full screen
Small screen
async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

Le code complet :

Copy
Full screen
Small screen
import fetch from "node-fetch";

const projectId = <your project_id from PA>;
const apiKey = <your api key from PA>;
const buff = new Buffer(`${projectId}:${apiKey}`);
const basicAuth = buff.toString('base64')

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function getItems() {
    // receive items from the original system or read from a pre-prepared file
    return items;
}

function prepareData(items) {
    // format items in accordance with API requirements
    return formatedItems;
}

async function createItem(item) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;

    return await fetch(url, {
        method: "POST",
        headers: {
            Authorization: "Basic " + basicAuth,
            "Content-Type": "application/json"
        },
        body: JSON.stringify(item),
    });
}

async function isItemExisted(sku) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;
    const response = await fetch(url, {
        method: "GET",
        headers: {
            Authorization: "Basic " + basicAuth
        }
    });
    return response.status !== 404;
}

async function createItems(items) {
    let success = 0;
    let alreadyCreated = 0;
    for (let i = 0; i < items.length; i++) {
        const item = items[i];
        if (item['sku'] === undefined) {
            console.log(`${i} Field "sku" not specified`);
            continue;
        }
        const sku = item['sku'];
        if (await isItemExisted(sku)) {
            console.log(`${i} Item with sku "${sku}" already created`);
            alreadyCreated++;
            continue;
        }
        const response = await createItem(item);
        if (response.status === 201) {
            console.log(`${i} Item with sku "${sku}" successfully created`)
            success++;
        } else {
            const jsonData = await response.json();
            console.log(`${i} An error occurred while creating the items with sku "${sku}"`);
            console.log(jsonData);
        }
        // add a delay so as not to run into rate limits
        await sleep(500);
    }
    console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);
}

async function run() {
  const items = await getItems();
  const formattedItems = prepareData(items);
  await createItems(formattedItems);
}

run(); 
Cet article vous a été utile ?
Merci !
Que pouvons-nous améliorer ? Message
Nous sommes désolés de l'apprendre
Dites-nous pourquoi vous n'avez pas trouvé cet article utile. Message
Merci pour votre commentaire !
Nous examinerons votre message et l'utiliserons pour améliorer votre expérience.
Dernière mise à jour: 8 Novembre 2024

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.

Signaler un problème
Nous améliorons continuellement notre contenu grâce à vos commentaires.
Indiquez votre adresse e-mail pour un suivi
Merci pour votre commentaire !