Katalog importieren

Erstellen und aktualisieren Sie einen Artikelkatalog durch einen JSON-Import

Sie können Artikel aus einer JSON-Datei importieren und so die Artikel erstellen, aktualisieren oder deaktivieren.

Dadurch können Sie:

Merkmale:

• Unterstützung für die folgenden Artikeltypen:
  • virtuelle Gegenstände
  • virtuelle Währung
  • virtuelle Währungspakete
  • Bundles
• Datenüberprüfung. Wenn die Dateistruktur oder das Datenformat den Anforderungen nicht entspricht, wird beim Importieren eine Liste mit Fehlern angezeigt.

Einschränkungen:

• Der Import von Spielschlüsseln, Werbeaktionen und Belohnungssystemen ist nicht möglich.
• Die Größe der hochgeladenen JSON-Datei darf maximal 7 MB betragen.
• Das Parameterformat in der JSON-Datei muss mit dem Format übereinstimmen, das in der entsprechenden Artikelerstellungsmethode angegeben ist:
  • Virtuellen Gegenstand erstellen
  • Virtuelle Währung erstellen
  • Virtuelles Währungspaket erstellen
  • Bundle erstellen

Artikelkatalog importieren

So importieren Sie einen Artikel aus einer Datei:

1. Öffnen Sie das Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Store und dann auf Virtuelle Währung, Virtuelle Gegenstände oder Bundles.
3. Klicken Sie auf Artikel importieren.

4. Wählen Sie eine Aktion:
   • Neue Artikel hinzufügen – nur Artikel mit neuen SKUs werden hinzugefügt.
   • Neue Artikel hinzufügen und vorhandene Artikel aktualisieren – Artikel mit neuen SKUs werden hinzugefügt und die Daten vorhandener Artikel werden aktualisiert.
   • Neue Artikel hinzufügen, vorhandene Artikel aktualisieren und fehlende Artikel deaktivieren – Artikel mit SKUs aus der Datei werden hinzugefügt/aktualisiert. Wenn ein Artikel im Katalog vorhanden ist, aber keine SKU in der Datei hinterlegt ist, wird der Status des Artikels im Kundenportal in Teilweise verfügbar geändert, d. h., der Artikel kann nicht einzeln gekauft werden, ist aber als Teil eines Bundles oder eines Bonus erhältlich.

5. Vervollständigen Sie die Datei für den Import:
   • Laden Sie die Dateivorlage im Download-Fenster herunter und vervollständigen Sie diese gemäß dem unten stehenden Beispiel.
   • Exportieren Sie die Artikel und verwenden Sie die exportierte Datei als Vorlage.
   • Erstellen Sie Ihre eigene JSON-Datei und vervollständigen Sie diese gemäß dem unten stehenden Beispiel.

Vervollständigte JSON-Datei (Beispie):

{
    "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
                }
            ]
        }
    ]
}

6. Laden Sie die vervollständigte Datei in das entsprechende Feld im Importfenster hoch.
7. Wenn beim Import Fehler auftreten, wird im Importfenster eine Liste dieser Fehler mitsamt Korrekturmaßnahmen angezeigt. Nehmen Sie die erforderlichen Änderungen an der Datei vor, und laden Sie diese erneut hoch.

Nach erfolgreichem Upload werden die Artikel mit den angegebenen SKUs erstellt, aktualisiert oder deaktiviert.

Artikelkatalog exportieren

So exportieren Sie einen Artikel oder den Artikelkatalog als JSON-Datei:

1. Öffnen Sie das Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Store und dann auf Virtuelle Währung, Virtuelle Gegenstände oder Bundles.
3. Klicken Sie auf Artikel exportieren.

4. Wählen Sie eine Aktion:
   • Alle Artikel exportieren – der gesamte Katalog mit allen Projektartikeln wird exportiert. Wenn Sie zum Beispiel zum Abschnitt Virtuelle Währung navigieren und alle Artikel exportieren, werden die virtuellen Währungen, die virtuellen Währungspakete, die virtuellen Gegenstände und die Spielschlüsselpakete des Projekts in die JSON-Datei geschrieben.
   • Nur ausgewählte Artikel exportieren – wählen Sie in dem sich öffnenden Fenster die zu exportierenden Artikel aus.

5. Klicken Sie auf Exportieren.

Daraufhin startet automatisch der Download der JSON-Datei.

Katalog aus externen Plattformen importieren

Sie können Artikel und Abonnements aus externen Plattformen importieren und das Benutzerinventar synchronisieren.

Katalog aus Google Play importieren

Achtung

Prüfen Sie, ob die Google Play Android Developer API in Ihrem Google Play-Projekt aktiviert ist, bevor Sie den Import starten. Besuchen Sie https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project={project_id}, wobei project_id Ihre Projekt-ID in Google Play ist. Falls die API deaktiviert ist, müssen Sie diese aktivieren. Es dauert eine Weile, bis die Einstellungen übernommen sind. Daher kann der Import fehlschlagen, wenn Sie sofort nach der Aktivierung versuchen, den Import zu starten. Warten Sie einige Minuten, und versuchen Sie es dann erneut.

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie im seitlichen Menü auf Online-Shop.
3. Klicken Sie im Bereich Katalogverwaltung auf Konfigurieren.
4. Klicken Sie im Bereich Integration in externe Plattformen auf Konfigurieren.
5. Klicken Sie im Bereich Google Play auf Konfigurieren.
6. Geben Sie Ihre Anwendungs-ID an – die ID Ihrer Anwendung aus Google Play.

7. Laden Sie einen privaten Schlüssel als JSON hoch.

8. Wechseln Sie zur Google Play Console, klicken Sie in der Seitenleiste auf Users and permissions und fügen Sie ein Dienstkonto als neuer Nutzer mit der Rolle Android Management User hinzu. Dazu muss Ihnen die Rolle Project IAM admin zugewiesen sein.

9. Klicken Sie auf Speichern.
10. Klicken Sie auf Import starten. Daraufhin beginnt der Katalogimport.

11. Um virtuelle Gegenstände in dem über den Site Builder erstellten Web Shop zu verkaufen, konfigurieren Sie Gegenstandsgruppen im Kundenportal und weisen Sie jedem Gegenstand mindestens eine der konfigurierten Gruppen zu.
12. Um die Gegenstandsbilder anzuzeigen, müssen Sie sie im Kundenportal zunächst hochladen.

Katalog aus dem App Store importieren

• Anwendungs-ID aus dem Abschnitt App Information in App Store Connect.
• API-Schlüssel und Issuer ID aus dem Abschnitt Users and Access in App Store Connect.

Anwendungs-ID besorgen

1. Melden Sie sich bei App Store Connect an.
2. Wechseln Sie zum Abschnitt Apps.
   
   

   

3. Öffnen Sie die Seite Ihrer Anwendung.
4. Navigieren Sie zu General Information > App Information.
5. Kopieren Sie unter General Information die Anwendungs-ID aus dem Feld Apple ID.
   
   

   

API-Schlüssel und Issuer ID besorgen

Die Issuer ID in App Store Connect wird für die Interaktion mit der Apple API verwendet, einschließlich der App Store Connect API. Sie ist für die Einrichtung von API-Schlüsseln erforderlich, um Aufgaben wie die App-Verwaltung, den Abruf von Analytics-Daten und andere Vorgänge in App Store Connect zu automatisieren.

Der API-Schlüssel ist eine eindeutige Kennung und dient dazu, API-Anfragen in App Store Connect API zu authentifizieren und einen sicheren Zugriff auf die Daten und Funktionen des Apple Developer Account zu gewährleisten.

Hier finden Sie die Issuer ID und den API-Schlüssel in App Store Connect:

1. Melden Sie sich bei App Store Connect an, und wechseln Sie zum Abschnitt Users and Access.
2. Öffnen Sie die Registerkarte Integrations.
3. Klicken Sie in der Seitenleiste unter Keys auf App Store Connect API.
4. Wechseln Sie zur Registerkarte Team Keys. Klicken Sie auf das +-Symbol, um einen neuen API-Schlüssel zu erstellen.
   
   

   

5. Vergeben Sie im Fenster Generate API Key einen Namen für den Schlüssel, und legen Sie die Zugriffsebene für diesen Schlüssel fest.
6. Klicken Sie auf Generate.
   
   

   

7. Der neu erstellte Schlüssel wird in der Liste der aktiven API-Schlüssel angezeigt. Laden Sie den Schlüssel als P8-Datei herunter, und kopieren Sie die Key ID.
   
   

   

8. Kopieren Sie die auf der Registerkarte Team Keys angezeigte Issuer ID.
   
   

   

Katalog aus dem App Store importieren

1. Öffnen Sie das Kundenportal, und navigieren Sie zu Store > Katalogverwaltung > Integration in externe Plattformen > App Store.
2. Geben Sie die Daten aus App Store Connect an:
   • Anwendungs-ID
   • Datei mit privatem Schlüssel (P8)
   • Herausgeber-ID (Issuer ID)
   • Key ID
3. Klicken Sie auf Import starten. Daraufhin startet der Katalogimport automatisch.
   
   

   

Um virtuelle Gegenstände in dem mit Site Builder erstellten Web Shop zu verkaufen, sollten Sie Gegenstandsgruppen im Kundenportal erstellen und jeden Gegenstand mindestens einer Gruppe zuweisen.

Damit Artikelbilder angezeigt werden, müssen Sie diese zuvor hochladen, indem Sie die importierten Artikel unter Store > Virtuelle Gegenstände bearbeiten.

Katalog aus PlayFab importieren

PlayFab bietet Spieleentwicklern fertige Serverlösungen für die Verwaltung von Katalogen und für die Monetarisierung. Nach der Integration von PlayFab können Sie einen Katalog aus PlayFab in Xsollas Store-Lösung importieren.

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie im seitlichen Menü auf Online-Shop.
3. Klicken Sie im Bereich Katalogverwaltung auf Konfigurieren.
4. Klicken Sie im Bereich Integration in externen Plattformen auf Konfigurieren.
5. Klicken Sie im Bereich PlayFab auf Konfigurieren.
6. Geben Sie auf der Registerkarte Artikelimport Folgendes an:
   • Titel-ID – Projekt-ID in PlayFab.
   • Geheimer Schlüssel – Schlüssel des Projekts in PlayFab.
7. Klicken Sie auf Speichern.
8. Synchronisieren Sie das Benutzerinventar mit PlayFab (optional):
   1. Wechseln Sie zur Registerkarte Inventarsynchronisierung und geben Sie Folgendes an:
      • Titel-ID – Projekt-ID in PlayFab.
      • Geheimer Schlüssel – Schlüssel des Projekts in PlayFab.
   2. Stellen Sie den Umschalter Benutzerinventar mit PlayFab synchronisieren auf Ein.
   3. Klicken Sie auf Speichern.
9. Wechseln Sie zur Registerkarte Artikelimport, und klicken Sie auf Import starten. Daraufhin beginnt der Katalogimport.
10. Um virtuelle Gegenstände in dem über den Site Builder erstellten Web Shop zu verkaufen, konfigurieren Sie Gegenstandsgruppen im Kundenportal und weisen Sie jedem Gegenstand mindestens eine der konfigurierten Gruppen zu.
11. Um die Gegenstandsbilder anzuzeigen, müssen Sie sie im Kundenportal zunächst hochladen.

Um zu prüfen, ob der Import erfolgreich abgeschlossen wurde, wechseln Sie über das seitliche Menü zum Abschnitt Online-Shop, und stellen Sie sicher, dass Gegenstände, Währungen und Bundles auf den Registerkarten Virtuelle Währung, Virtuelle Gegenstände und Bundles aktiviert sind.

Katalog neu importieren

Wenn Sie einen Katalog neu importieren, ist Folgendes zu beachten:

• Bereits im Online-Shop befindliche Artikel werden aktualisiert.
• Noch nicht im Online-Shop befindliche Artikel werden hinzugefügt.
• Aus der Importquelle entfernte Artikel verbleiben im Online-Shop. Solche Artikel können Sie im Kundenportal oder über die API löschen.

Artikel automatisch über API erstellen

Wenn Sie eine Vielzahl von Artikeln auf der Grundlage von Daten aus Ihrem System erstellen müssen, können Sie den Vorgang mithilfe der API automatisieren.

Dazu müssen Sie:

• die Artikeldaten aus Ihrem System exportieren,
• die exportierten Daten in ein Format konvertieren, das dem Datenformat der API-Methode des gewünschten Artikeltyps entspricht,
• ein Skript erstellen, das die erforderliche API-Methode für jeden exportierten Artikel aufruft:
  • Virtuellen Gegenstand erstellen
  • Virtuelle Währung erstellen
  • Virtuelles Währungspaket erstellen
  • Bundle erstellen

Wenn Sie Gegenstandsgruppen verwenden möchten, müssen Sie diese im Voraus im Kundenportal erstellen.

Wenn Sie mehrere Artikeltypen verwenden möchten, sollten diese in der folgenden Reihenfolge erstellt werden:

1. Gegenstandsgruppen im Kundenportal
2. virtuelle Währungen
3. virtuelle Gegenstände
4. virtuelle Währungspakete
5. Bundles

Nachfolgend sehen Sie ein Beispielskript, das wiederholt die Methode Virtuellen Gegenstand erstellen aufruft, um virtuelle Gegenstände zu erstellen.

Das Skript wurde mit JavaScript und Node.js, der JavaScript-Laufzeitumgebung, entwickelt.

1. Importieren Sie die fetch-Funktion des Moduls “node-fetch”, um HTTP-Anfragen an den Xsolla-Server senden zu können.

import fetch from "node-fetch";

2. Legen Sie die für die Anfrageautorisierung benötigten Konstanten fest. Fügen Sie anstelle von <your project_id from PA> und <your api key from PA> Ihre Werte für die Projekt-ID und den API-Schlüssel ein, die für die spätere Verwendung in API-Anfragen mit Base64 kodiert werden.

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')

3. Implementieren Sie die Hilfsfunktion sleep. Diese dient dazu, das Senden von Anfragen zu verzögern. Das ist notwendig, um die Ratenbegrenzung bei API-Anfragen nicht zu überschreiten.

function sleep(ms) {

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

}

4. Implementieren Sie die Funktion getItems, um Artikeldaten aus Ihrem System abzurufen.

async function getItems() {

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

   return items;

}

5. Implementieren Sie die für Ihr System spezifische Funktion prepareData, um die Artikeldaten gemäß dem erforderlichen Datenformat des API-Aufrufs Virtuellen Gegenstand erstellen zu formatieren.

function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}

6. Ergänzen Sie die Funktion createItem. Diese Funktion sendet eine POST-Anfrage an die Xsolla-API, um einen virtuellen Gegenstand zu erstellen.

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),

   });

}

7. Ergänzen Sie die Funktion checkItemExist, um zu prüfen, ob ein virtueller Gegenstand mit der angegebenen SKU existiert. Die Funktion sendet eine GET-Anfrage an die Xsolla-API:
   • Enthält die Antwort den HTTP-Statuscode 404, wurde der Gegenstand mit der angegebenen SKU nicht gefunden und muss erstellt werden.
   • Enthält die Antwort den HTTP-Statuscode 200, wurde der Gegenstand mit der angegebenen SKU gefunden und muss nicht erstellt werden.

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;

}

8. Ergänzen Sie die Funktion createItems, die die Liste der Gegenstände durchgeht und prüft, ob es aufseiten von Xsolla einen Gegenstand mit einer SKU aus Ihrem System gibt. Wurde kein Gegenstand mit einer solchen SKU gefunden, erstellt die Funktion einen Gegenstand. Der Fortschritt wird in der Konsole angezeigt.

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`);

}

9. Ergänzen Sie die Funktion run. Diese Funktion ruft alle oben genannten Funktionen in der richtigen Reihenfolge auf.

async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

Der vollständige Code:

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();