Infoplay

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.

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 ] });
    });

});

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

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

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

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.