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.
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 :
- L’importation n’est pas disponible pour les clés de jeu, les promotions et les systèmes de récompense.
- La taille du fichier JSON téléchargé ne doit pas dépasser 7 Mo.
- Le format des paramètres dans le fichier JSON doit correspondre au format spécifié dans la méthode de création du produit correspondant :
Importation du catalogue des objets
Pour importer un catalogue des objets à partir d’un fichier :
- Ouvrez le projet dans le Compte éditeur.
- Dans le menu latéral, cliquez sur Store et accédez à la section Virtual currency, Virtual items ou Bundles.
- Cliquez sur Import items.
- 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.
- 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 :
- json
{
"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
}
]
}
]
}
- Téléchargez le fichier dans le champ correspondant de la fenêtre d’importation.
- 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.
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 :
- Ouvrez le projet dans le Compte éditeur.
- Dans le menu latéral, cliquez sur Store et accédez à la section Virtual currency, Virtual items ou Bundles.
- Cliquez sur Export items.
- 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.
- 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.
- réimportez le catalogue (sauf les abonnements) ;
- apportez des modifications au catalogue dans le Compte éditeur manuellement ;
- apportez des modifications au catalogue manuellement à l’aide de groupes de méthodes API pour la gestion des lots, des objets virtuels et des monnaies virtuelles, desplans d’abonnement, et des produits d’abonnement.
Importer un catalogue depuis Google Play
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.
- Ouvrez le projet dans votre Compte éditeur.
- Cliquez sur Store dans le menu latéral.
- Dans le volet Catalog Management, cliquez sur Configure.
- Dans le volet Integration with external platforms, cliquez sur Configure.
- Dans le volet Google Play, cliquez sur Configure.
- Spécifiez Application ID, c'est-à-dire l'identifiant de votre application sur Google Play.
- Téléchargez un fichier JSON avec la clé privée.
- 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.
- Cliquez sur Save.
- Cliquez sur Start import. L'importation du catalogue démarre automatiquement.
- 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.
- Pour afficher les images des objets, téléchargez-les vers votre Compte éditeur.
Importer un catalogue depuis App Store
- ID d’application à partir de la section App Information dans App Store Connect ;
- Clé API et Issuer ID à partir de la section Users and Access dans App Store Connect.
Obtenir l'ID de l'application
Pour obtenir votre ID d’application dans App Store Connect :- Connectez-vous à App Store Connect.
- Accédez à la section Apps.
- Ouvrez la page de votre application.
- Naviguez vers General Information > App Information.
- 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 :
- Connectez-vous à App Store Connect et accédez à la section Users and Access.
- Ouvrez l’onglet Integrations.
- Dans le menu latéral Keys, cliquez sur App Store Connect API.
- Accédez à l’onglet Team Keys. Cliquez sur l’icône + pour créer une nouvelle clé API.
- Dans la fenêtre Generate API Key, attribuez un nom à la clé et définissez son niveau d’accès.
- Cliquez sur Generate.
- 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.
- Dans l’onglet Team Keys, copiez l’Issuer ID.
Importer un catalogue depuis l'App Store
- Ouvrez le Compte éditeur et accédez à Store > Catalog management > Integration with external platforms > App Store.
- Fournissez les données obtenues dans App Store Connect :
- ID d’application ;
- Fichier de clé privée (P8) ;
- Issuer ID ;
- Key ID.
- 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.
Importer un catalogue depuis PlayFab
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 :
- Exporter les données sur les objets depuis votre système.
- Convertir les données exportées dans un format correspondant à celui des données de la méthode API pour le type d’objet requis.
- Créer un script qui appelle la méthode API requise pour chaque objet exporté :
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 :
- Groupes d’objets dans le Compte éditeur.
- Monnaies virtuelles.
- Objets virtuels.
- Packages de monnaie virtuelle.
- 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.
- Importez la fonction
fetch
du module“node-fetch”
pour envoyer des requêtes HTTP au serveur Xsolla.
- javascript
import fetch from "node-fetch";
- 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.
- javascript
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')
- 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.
- javascript
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
- Implémentez la fonction
getItems
, spécifique à votre système, pour récupérer les données des objets depuis votre système.
- javascript
async function getItems() {
// receive items from the original system or read from a pre-prepared file
return items;
}
- 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.
- javascript
function prepareData(items) {
// format items in accordance with API requirements
return formattedItems;
}
- Ajoutez la fonction
createItem
, qui envoie une requêtePOST
à l’API Xsolla pour créer un objet virtuel.
- javascript
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),
});
}
- Ajoutez la fonction
checkItemExist
, qui vérifie l’existence d’un objet virtuel avec une UGS spécifique. Cette fonction envoie une requêteGET
à 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éé.
- Si la réponse retourne un code HTTP
- javascript
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;
}
- 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.
- javascript
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`);
}
- Ajouter la fonction
run
qui appelle toutes les fonctions ci-dessus dans le bon ordre.
- javascript
async function run() {
const items = await getItems();
const formattedItems = prepareData(items);
await createItems(formattedItems);
}
Le code complet :
- javascript
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();
Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entée.