2. Knowledge Base
  3. Integrationshandbuch
  4. Produkte
  5. Infoplay

Infoplay

Produkte ZBWVM
Zurück
Allgemeines

Infoplay bietet eine produktbezogene Integration Ihrer Daten. Konkret bedeutet das, dass Sie mit Infoplay etwa Artikelnummern aus Dokumenten, Stories oder Exposés mit Produktdaten aus Ihrem System (z. B. Onlineshop oder ERP) verknüpfen können. Weiterhin kann ein Anwender mit einem Klick auf den Bestell-Button im Infoplay-Dialog direkt dieses Produkt in seinen Warenkorb legen, ohne Umwege über die Produktsuche Ihres Systems.

Die Warenkorbübergabe ist nur eine der Möglichkeiten, die Sie hierbei nutzen können. Daneben können Sie auch eine einfache Hyperlink-Verknüpfung mit einer Produkt-Detailseite herstellen. Darüber hinaus können via Infoplay Direct Produktkacheln und Datenblätter in OXOMI Integrationen wie Stories, Universal Search und Navigator Pro mit Preis- und Verfügbarkeitsinformationen angereichert werden.

Die Beschreibung setzt die Grundlagen des Artikels JavaScript Integrationsgrundlagen voraus. Der Artikel geht dabei insbesondere auf die Parameter (sowie deren Wertebereich) der vorhandenen Integrationsmöglichkeiten ein und veranschaulicht diese jeweils mithilfe eines Beispiels.

Zusätzlich setzt die Beschreibung die Grundlagen des Artikels BUZZ Schnittstelle voraus, denn die Anbindung von Infoplay erfolgt mittels der scireum BUZZ Schnittstelle. Diese ermöglicht eine einfache und asynchrone Kommunikation - sowohl zwischen Anwendungen im Browser, als auch mit nativen Anwendungen oder Apps, welche entsprechende Callbacks im Browser hinterlegen.

Anreichern von Artikeldaten

Mit der Capability enhanceProductData können die Daten eines Produktes erweitert werden. Insbesondere können Preis und Verfügbarkeit angezeigt werden.

In der empfangenen Nachricht stehen die folgenden Informationen:

Feld Beschreibung
itemNumber Enthält die Artikelnummer des angefragten Produktes.
gtin Enthält die GTIN des angefragten Produktes, falls am Produkt hinterlegt.
supplierNumber

Enthält die Nummer des Lieferanten, für den die Anfrage gestellt wurde. Diese wird in der Partnerschaft hinterlegt (andernfalls ist diese „-“). Bei eigenen Produkten ist diese auch „-“.

supplierNumbers

Sind in der Partnerschaft mehrere Lieferantennummern hinterlegt, so werden hier alle Nummern als kommaseparierte Liste übertragen. In diesem Fall enthält supplierNumber die erste Nummer.

brand.name Enthält den Markennamen des Herstellers.
scope

Definiert den Umfang der Daten die an der angefragten Stelle angezeigt werden können. Dies erlaubt es, bestimmte, komplexer zu berechnende Informationen nur dann zu laden, wenn diese letztendlich auch angezeigt werden. Mögliche Werte:

Wert Beschreibung
compact Die Informationen werden in einer Produkt-Kachel (z. B. in einer Story oder im Navigator Pro) oder Tabelle angezeigt. Hierbei entfällt etwa die Anzeige von Zusatz-Feldern (additionalFields) oder dem Mengenfeld am Bestell-Button.
full Die Informationen werden in einer vollumfänglichen Ansicht, wie etwa im Infoplay-Dialog oder der Produkt-Detailseite, angezeigt. Hierbei können alle verfügbaren Informationen angezeigt werden.

Als Ergebnis kann eine Nachricht mit den folgenden Informationen zurückgegeben werden:

Feld Beschreibung
itemNumber Kann verwendet werden, um die angezeigte Herstellerartikelnummer zu überschreiben.
gtin Kann verwendet werden, um die angezeigte Hersteller-GTIN zu überschreiben.
model Kann verwendet werden, um die angezeigte Hersteller-Type zu überschreiben.
shortText Kann verwendet werden, um den angezeigten Hersteller-Kurztext zu überschreiben.
price.prefix

Gibt ein Präfix für den Hauptpreis (z. B. zzgl. MwSt.) an.

Hinweis:

  • Dies wird nur benötigt, wenn Sie auch einen alternativePrice angeben. Bei lediglich einem Preis sollte auf das Präfix verzichtet werden, damit die Darstellung übersichtlicher bleibt.
price.amount Gibt den Preis des Produktes an. Dieser sollte zur Anzeige für den Benutzer formatiert (inkl. Währungssymbol) sein.
priceQuantity Gibt die Bezugsmenge des Preises an. Beispiel: "je 1 Stück". Auch diese sollte fertig zur Anzeige beim Benutzer formatiert sein.
alternativePrice.prefix Gibt ein Präfix für den Alternativ-Preis (z. B. inkl. MwSt.) an.
alternativePrice.amount

Gibt den Alternativ-Preis des Produktes an. Dieser sollte zur Anzeige für den Benutzer formatiert sein.

Hinweis:

  • Den Alternativ-Preis sollten Sie nur verwenden, wenn dies unbedingt erforderlich ist (z. B. zur Ausgabe des Preises inkl. MwSt. in öffentlichen Portalen). Die Ausgabe von zwei Preisen kann teilweise für den Benutzer unübersichtlich wirken.
availability.state

Gibt die Farbe der Verfügbarkeitsampel vor. Mögliche Werte:

Wert Beschreibung Darstellung
unknown Derzeit keine Information zur Verfügbarkeit vorhanden.
/
no_longer_available Das Produkt ist nicht mehr auf Lager und wird auch nicht mehr produziert.
/
made_to_order Das Produkt wird bei Bestellung gefertigt.
/
out_of_stock Das Produkt ist nicht mehr auf Lager.
/
low Das Produkt ist nur noch in geringer Stückzahl verfügbar.
/
full Das Produkt ist in ausreichender Stückzahl verfügbar.
/
availability.fromSupplier Gibt an, dass sich die Verfügbarkeit nicht auf das eigene Lager, sondern auf den Hersteller selbst bezieht. Dies wird durch entsprechende Icons signalisiert.
availability.text Gibt eine ergänzende Verfügbarkeitsmeldung aus.
order.quantity

Gibt die empfohlene Bestellmenge an. Diese sollte fertig formatiert sein, da dieser Wert dem Benutzer im Eingabefeld angezeigt wird. Die Mengeneinheit wird in order.unit angegeben und sollte hier nicht enthalten sein. Wenn es keine Vorschlagsmenge gibt, können Sie einen leeren String angeben.

Hinweis:

  • Beachten Sie, dass bestimmte Integrationen nur das Warenkorb-Symbol ohne Eingabefeld anzeigen. In diesem Fall wird dieser Wert ignoriert.
  • Wenn Sie weder order.quantity nochorder.unit angeben (also keinorder Unterobjekt am Produkt hinterlegen), wird das Produkt als „nicht bestellbar“ angesehen und kein Warenkorb-Symbol angezeigt. Alternativ können Sie in einem solchen Fall auch gezieltorder = false angeben.
order.unit Gibt die Mengeneinheit an, in der bestellt wird. Diese wird als Hinweise neben dem Eingabefeld angezeigt.
additionalFields Enthält ein Array (z. B. [{label: 'Feldname', text: 'Wert'}], welches als weitere Name-Wert-Paare auf der Detailseite des Produktes anzeigt wird.
datasheetUrl Kann verwendet werden, um einen Link zum Datenblatt des Produktes anzugeben. Dieser wird dann als Button im Infoplay Dialog angezeigt.
canJumpToProduct Kann verwendet werden, um den Button zum Springen zum Produkt anzuzeigen oder zu verbergen. Standardmäßig wird dieser Button angezeigt, wenn die Capability jumpToProduct gesetzt ist. Siehe auch Sprung zum Produkt.

Beispiel:

shop.addCapability('enhanceProductData', function (message) {
    const product = message.payload();

    product.gtin = "alternative GTIN";
    product.itemNumber = "alternative Artikelnummer";
    product.model = "alternative Type";
    product.shortText = "alternativer Kurztext";
    product.availability = {
        state: "full",
        text: "Ausreichend auf Lager"
    };
    product.price = {
        prefix: "zzgl. MwSt.",
        amount: "100,00 EUR",
    };
    product.alternativePrice = {
        prefix: "inkl. MwSt.",
        amount: "119,00 EUR",
    };
    product.priceQuantity = "je 1 Stück";
    product.order = {
        quantity: "10",
        unit: "Stück"
    };

    message.reply(product);
});

Sollte in Ihrem System keinen Verfügbarkeitsinformationen vorliegen, oder das Produkt als ausverkauft gemeldet werden, so können Sie mittels oxomi.productAvailability weitere Verfügbarkeiten des Herstellers über OXOMI Blink anfragen und in Ihre Antwort einfließen lassen (siehe Herstellerverfügbarkeiten - OXOMI Blink).

Interaktives Code-Beispiel

Beispiel: 

shop.addCapability('fetchProductData', function (message) {
    const request = message.payload();

    const product = {
        // ... (siehe oben)
    };

    // Verfügbarkeit von OXOMI laden, falls lokal keine bekannt ist...
    oxomi.productAvailability({
        itemNumber1: request.itemNumber,
        supplierNumber1: request.supplierNumber,
        cached: true
    }).then((blinkResponse) => {
        product.availability = {
            state: blinkResponse.items[0].stockIndicator,
            text: blinkResponse.items[0].stockMessage
        };

        message.reply({ products: [ product ] });
    });

});
Hinzufügen zum Warenkorb

Mit der Capability addProductToBasket werden Produkte in den Warenkorb gelegt. Ein Warenkorb wird angezeigt, wenn Sie für ein Produkt in enhanceProductData bei order.quantity und/oder order.unit einen Wert angeben. Als Nachricht, wird das komplette Ergebnis von enhanceProductData erneut übermittelt. Wenn Sie also hier dem Objekt weitere Attribute hinzufügen, können Sie diese hier erneut abfragen.

In der empfangenen Nachricht stehen die folgenden Informationen:

Feld Beschreibung
product.* Prinzipiell enthält die Nachricht alle Felder, die in enhanceProductData gefüllt werden, auch solche, die von OXOMI selbst nicht verarbeitet oder angezeigt werden. Falls nicht überschrieben, werden die Felder itemNumber, supplierNumber, supplierNumbers, gtin und brand.name aus der ursprünglichen Anfrage übernommen.
product.order.quantity Falls ein Mengeneingabefeld verfügbar war (z. B. im Produktdatenblatt), wird hier die gewünschte Bestellmenge (als benutzer-formatierte Eingabe) übermittelt. Wenn kein Eingabefeld angezeigt wird, aber in enhanceProductData eine Menge angegeben wurde, wird diese hier übermittelt.

Beispiel:

shop.addCapability('addProductToBasket', function (message) {
    const product = message.payload().product;
    // TODO handle product...
});

Hier wird keine Rückgabe oder Antwort erwartet.

Interaktives Code-Beispiel

Sprung zum Produkt

Mittels der Capabilities jumpToProduct und provideJumpToProductLabel kann der Infoplay-Dialog und der Kopfbereich des Datenblatts um eine Schaltfläche erweitert werden, die den Benutzer direkt zum Produkt springen lässt.

Die Capability provideJumpToProductLabel legt hierbei den Text für die Schaltfläche fest und jumpToProduct die auszuführende Logik beim Klick auf die Schaltfläche.

Sind beide Capabilities gesetzt, wird die Schaltfläche im Kopfbereich des Datenblatts und im Infoplay-Dialog angezeigt. Darüber ist es unter anderem möglich, den Nutzer direkt zur erweiterten Produktdetailseite auf ihrer Website zu leiten, aber auch andere über JavaScript lösbare Aktionen sind denkbar.

Wird die Schaltfläche vom Nutzer betätigt, wird die Capability jumpToProduct mit den folgenden Informationen als Nachricht aufgerufen:

Feld Beschreibung
product.* Prinzipiell enthält die Nachricht alle Felder, die in enhanceProductData gefüllt werden, auch solche, die von OXOMI selbst nicht verarbeitet oder angezeigt werden. Falls nicht überschrieben, werden die Felder itemNumber, supplierNumber, supplierNumbers, gtin und brand.name aus der ursprünglichen Anfrage übernommen.

Beispiel:

shop.addCapability('provideJumpToProductLabel', function (message) {
    message.reply({label: 'Zum Produkt'});
});
shop.addCapability('jumpToProduct', function (message) {
    const product = message.payload().product;

    // Zum Produkt springen...
    window.open('/product/' + product.supplierNumber + '/' + product.itemNumber);
});

Hier wird keine Rückgabe oder Antwort erwartet.

Interaktives Code-Beispiel Interaktives Code-Beispiel

Vollständige Artikeldaten

Mit der Capability fetchProductData können die Daten eines Produktes abgerufen werden. Die Capability wird verwendet, wenn eine Artikelnummer in einem Dokument oder Exposé angeklickt wird. Wenn diese Capability nicht vorhanden ist, oder ein leeres Ergebnis liefert, wird das Produkt in OXOMI Data gesucht und anschließend mit enhanceProductData erweitert. Dieser Callback kann also insbesondere verwendet werden, wenn die eigenen Daten bevorzugt vor den OXOMI-Daten angezeigt werden sollen, oder wenn Daten geliefert werden können, die nicht in OXOMI verfügbar sind.

Die Daten sind im Wesentlichen dieselben, wie bei enhanceProductData, jedoch können hier mehrere Produkte zurückgegeben werden, falls die Artikelnummer nicht eindeutig ist. Weiterhin kann zusätzlich mit previewImageUrl ein Vorschaubild und mittels brand Marken-Informationen angegeben werden.

In der empfangenen Nachricht stehen die folgenden Informationen:

Feld Beschreibung
itemNumber Enthält die Artikelnummer des angefragten Produktes.
supplierNumber

Enthält die Nummer des Lieferanten, für den die Anfrage gestellt wurde. Diese wird in der Partnerschaft hinterlegt (andernfalls ist diese "-"). Bei eigenen Produkten ist diese auch "-".

supplierNumbers

Sind in der Partnerschaft mehrere Lieferantennummern hinterlegt, so werden hier alle Nummern als kommaseparierte Liste übertragen. In diesem Fall enthält supplierNumber die erste Nummer.

Als Ergebnis kann entweder eine Liste mit einem oder mehreren Produkten als {products: [product1, product2]} übergeben werden, oder ein komplett leeres Objekt, also {}, falls OXOMI selbst nach dem Produkt suchen soll.

Ein einzelnes Produkt kann wie folgt aussehen:

Feld Beschreibung
itemNumber Gibt die effektive Artikelnummer aus.
gtin Gibt die anzuzeigende GTIN an.
model Gibt die Type oder Modellnummer des Produktes an.
shortText Enthält den Kurztext des Produktes.
previewImageUrl Enthält die URL zum Vorschaubild des Produktes.
brand.name Enthält den Markennamen des Herstellers.
brand.imageUrl Enthält die URL zum Markenlogo des Herstellers.
price.prefix

Gibt ein Präfix für den Hauptpreis (z. B. zzgl. MwSt.) an.

Hinweis:

  • Dies wird nur benötigt, wenn Sie auch einen alternativePrice angeben. Bei lediglich einem Preis sollte auf das Präfix verzichtet werden, damit die Darstellung übersichtlicher bleibt.
price.amount Gibt den Preis des Produktes an. Dieser sollte zur Anzeige für den Benutzer formatiert (inkl. Währungssymbol) sein.
priceQuantity Gibt die Bezugsmenge des Preises an. Beispiel: "je 1 Stück". Auch diese sollte fertig zur Anzeige beim Benutzer formatiert sein.
alternativePrice.prefix Gibt ein Präfix für den Alternativ-Preis (z. B. inkl. MwSt.) an.
alternativePrice.amount

Gibt den Alternativ-Preis des Produktes an. Dieser sollte zur Anzeige für den Benutzer formatiert sein.

Hinweis:

  • Den Alternativ-Preis sollten Sie nur verwenden, wenn dies unbedingt erforderlich ist (z. B. zur Ausgabe des Preises inkl. MwSt. in öffentlichen Portalen). Die Ausgabe von zwei Preisen kann teilweise für den Benutzer unübersichtlich wirken.
availability.state

Gibt die Farbe der Verfügbarkeitsampel vor. Mögliche Werte:

Wert Beschreibung Darstellung
unknown Derzeit keine Information zur Verfügbarkeit vorhanden.
/
no_longer_available Das Produkt ist nicht mehr auf Lager und wird auch nicht mehr produziert.
/
made_to_order Das Produkt wird bei Bestellung gefertigt.
/
out_of_stock Das Produkt ist nicht mehr auf Lager.
/
low Das Produkt ist nur noch in geringer Stückzahl verfügbar.
/
full Das Produkt ist in ausreichender Stückzahl verfügbar.
/
availability.fromSupplier Gibt an, dass sich die Verfügbarkeit nicht auf das eigene Lager, sondern auf den Hersteller selbst bezieht. Dies wird durch entsprechende Icons signalisiert.
availability.text Gibt eine ergänzende Verfügbarkeitsmeldung aus.
order.quantity

Gibt die empfohlene Bestellmenge an. Diese sollte fertig formatiert sein, da dieser Wert dem Benutzer im Eingabefeld angezeigt wird. Die Mengeneinheit wird in order.unit angegeben und sollte hier nicht enthalten sein. Wenn es keine Vorschlagsmenge gibt, können Sie einen leeren String angeben.

Hinweis:

  • Beachten Sie, das bestimmte Integrationen nur das Warenkorb-Symbol ohne Eingabefeld anzeigen. In diesem Fall wird dieser Wert ignoriert.
  • Wenn Sie weder order.quantity noch order.unit angeben (also kein order Unterobjekt am Produkt hinterlegen), wird das Produkt als „nicht bestellbar“ angesehen und kein Warenkorb-Symbol angezeigt. Alternativ können Sie in einem solchen Fall auch gezielt order = false angeben.
order.unit Gibt die Mengeneinheit an, in der bestellt wird. Diese wird als Hinweise neben dem Eingabefeld angezeigt.
additionalFields Enthält ein Array (z. B. [{label: 'Feldname', text: 'Wert'}], welches als weitere Name-Wert-Paare auf der Detailseite des Produktes anzeigt wird.
datasheetUrl Kann verwendet werden, um einen Link zum Datenblatt des Produktes anzugeben. Dieser wird dann als Button im Infoplay Dialog angezeigt.
canJumpToProduct Kann verwendet werden, um den Button zum Springen zum Produkt anzuzeigen oder zu verbergen. Standardmäßig wird dieser Button angezeigt, wenn die Capability jumpToProduct gesetzt ist. Siehe auch Sprung zum Produkt.

Beispiel:

shop.addCapability('fetchProductData', function (message) {
    const product = {
        gtin: "GTIN",
        itemNumber: "Artikelnummer",
        model: "Type",
        shortText: "Kurztext",
        previewImageUrl: "https://...",
        brand: {
            name: "Hersteller",
            imageUrl: "https://..."
        },
        availability: {
            state: "full",
            text: "Ausreichend auf Lager"
        },
        price: {
            prefix: "zzgl. MwSt.",
            amount: "100,00 EUR",
        },
        alternativePrice: {
            prefix: "inkl. MwSt.",
            amount: "119,00 EUR",
        },
        priceQuantity: "je 1 Stück",
        order: {
            quantity: "10",
            unit: "Stück"
        }
    };

    message.reply({ products: [ product ] });
});

Genau wie bei enhanceProductData kann auch hier oxomi.productAvailability verwendet werden, um Herstellerverfügbarkeiten nachzuladen, falls keine Informationen vorliegen.

Interaktives Code-Beispiel

Gesamtpreis berechnen

Mit der Capability calculateTotalPrice kann der Gesamtpreis der übergebenen Produkte angegeben werden. Die Capability wird verwendet, wenn ein Artikel der Merkliste hinzugefügt, entfernt oder dessen Bestellanzahl erhöht wird. Wenn diese Capability nicht vorhanden ist, oder ein leeres Ergebnis liefert, wird der Gesamtpreis nicht angezeigt.

In der empfangenen Nachricht stehen die folgenden Informationen:

Feld Beschreibung
products

Eine Liste von Produkten, für die der Gesamtpreis berechnet werden soll. Jedes Produkt enthält die folgenden Felder:

Wert Beschreibung
itemNumber Enthält die Artikelnummer des angefragten Produktes.
supplierNumber Enthält die Nummer des Lieferanten, für den die Anfrage gestellt wurde. Diese wird in der Partnerschaft hinterlegt (andernfalls ist diese "-"). Bei eigenen Produkten ist diese auch "-".

Als Ergebnis kann eine Nachricht mit den folgenden Informationen zurückgegeben werden:

Feld Beschreibung
price.prefix

Gibt ein Präfix für den Hauptpreis (z. B. zzgl. MwSt.) an.

Hinweis:

  • Dies wird nur benötigt, wenn Sie auch einen alternativePrice angeben. Bei lediglich einem Preis sollte auf das Präfix verzichtet werden, damit die Darstellung übersichtlicher bleibt.
price.amount Gibt den Gesamtpreis der Produkte an. Dieser sollte zur Anzeige für den Benutzer formatiert (inkl. Währungssymbol) sein.
alternativePrice.prefix Gibt ein Präfix für den Alternativ-Preis (z. B. inkl. MwSt.) an.
alternativePrice.amount

Gibt den Alternativ-Gesamtpreis der Produkte an. Dieser sollte zur Anzeige für den Benutzer formatiert sein.

Hinweis:

  • Den Alternativ-Preis sollten Sie nur verwenden, wenn dies unbedingt erforderlich ist (z. B. zur Ausgabe des Preises inkl. MwSt. in öffentlichen Portalen). Die Ausgabe von zwei Preisen kann teilweise für den Benutzer unübersichtlich wirken.
Siehe auch
Enthält die Grundlagen zum Thema Javascript Integration.
Beschreibt die verschiedenen Integrationen zur Anzeige des Produkt-Datenblatts.
Enthält Informationen über die BUZZ Schnittstelle.
Enthält Informationen über die Integration von Dokumenten.
Enthält Informationen über die Integration von Herstellerverfügbarkeiten.