Das JavaScript-SDK nutzen

Alles, was bluebarry in deinem Shop zeigt (Quizze, Suche, Produkt-Chat und Popups), läuft über ein kleines Skript. Dieses Skript gibt deinem Entwicklerteam auch einen JavaScript-Helfer auf der Seite, window.barry, um ein Quiz aus eigenem Code zu öffnen, bluebarry mitzuteilen, wer ein Besucher ist, oder eine Bestellung zu erfassen. Die meisten Shops brauchen das nie. Dieser Artikel ist für den Moment, in dem du es doch brauchst.

Das Skript laden

Auf Shopify, WooCommerce, CCV Shop und Magento lädt die App, das Plugin, das Modul oder die Integration das Skript schon. Überall sonst kopierst du das Funnel script aus dem Tab Launch eines Quiz und fügst es in den <head> jeder Seite ein. Kurz gesagt macht es Folgendes:

<script>
  window.barry = window.barry || {};
  window.barry.tenantId = "YOUR_TENANT_ID";
</script>
<script async src="https://api.bluebarry.ai/sdk/YOUR_TENANT_ID/advisor.js"></script>

• Das Skript lädt im Hintergrund und holt nur die Teile, die dein Shop nutzt. Siehe Für einen schnellen Shop entwickelt.
• Versehentlich doppelt eingebaut? Kein Problem: Die erste Kopie gilt.
• Ruf die Methoden unten aus einem Klick-Handler oder nach dem Laden der Seite auf, damit das Skript da ist, wenn dein Code läuft.

Ein Quiz öffnen

Für einen Quiz-Button brauchst du keinen Code: Ein Link auf #bluebarry:QUIZ_ID öffnet das Quiz. Für eigene Buttons und Ereignisse nutzt du openAdvisor. Die Quiz-ID steht im Quiz-Link im Tab Implementation.

barry.openAdvisor("QUIZ_ID");

// Produkt-Check: nach einem bestimmten Produkt fragen
barry.openAdvisor("QUIZ_ID", "PRODUCT_ID");

// Neu starten statt frühere Antworten fortzusetzen
barry.openAdvisor("QUIZ_ID", undefined, { restart: true });

Mit ein paar Hooks kann deine Seite auf das Quiz reagieren:

barry.onOpened = (quiz) => { /* das Quiz-Overlay hat sich geöffnet */ };
barry.onResultOpened = (result) => { /* die Ergebnisse werden angezeigt */ };
barry.onClosed = () => { /* das Quiz-Overlay wurde geschlossen */ };

// Das Quiz nicht wieder öffnen, wenn jemand mit dem Zurück-Button zurückkommt
barry.autoOpenOnBackNavigation = false;

bluebarry sagen, wer ein Besucher ist

Meldet sich jemand an oder abonniert deinen Newsletter, übergib die E-Mail-Adresse. bluebarry verknüpft sie mit dem Besucher, sodass Surfen, Suchen und Quiz-Antworten in einem Kundenprofil zusammenlaufen. Mach das nur für Personen, die zugestimmt haben.

barry.identify({ email: "[email protected]" });

Mehr dazu in Die Identify-API nutzen.

Eine Bestellung erfassen

Shopify und WooCommerce senden Bestellungen automatisch an bluebarry. Auf anderen Plattformen rufst du trackConversion auf der Bestellbestätigungsseite auf, mit den echten Bestelldaten:

barry.trackConversion({
  conversionId: "ORDER-12345",
  currencyIso: "EUR",
  orderProductTotal: 250.00,
  orderTaxTotal: 62.50,
  orderGrandTotal: 312.50,
  items: [
    { itemId: "SKU-001", quantity: 2, priceExclTax: 100.00, priceInclTax: 125.00, taxPercentage: 25 },
  ],
});

bluebarry verknüpft die Bestellung mit dem Quiz, das die Person gemacht hat, auch wenn das Tage her ist. Ist das Hauptskript nicht auf deiner Bestätigungsseite, nimm das fertige Skript aus Performance-Tracking-Skript einbauen.

Die Suche öffnen

Ist die Suche live, hängt sie sich von selbst an das Suchfeld deines Shops. Diese Methoden brauchst du, wenn du einen eigenen Such-Button hast oder die volle Ergebnisseite auf einer eigenen Seite zeigen willst:

barry.openSearch();
barry.closeSearch();

<!-- Auf deiner Suchergebnisseite -->
<div data-bluebarry-serp></div>

Das Einrichtungs-Snippet findest du in Suche in deinem Shop live schalten.

Produkt-Chat

Öffne oder schließe den Chat über einen eigenen Button oder gib ihm einen festen Platz auf der Seite:

barry.openChat();
barry.closeChat();

// Ist der Chat auf dieser Seite verfügbar? "ready", "disabled", "error" oder "missing_target"
barry.chatStatus?.state;

<!-- Wo der eingebettete Chat erscheinen soll, zum Beispiel über dem Produktraster -->
<div data-bluebarry-product-chat-embed></div>

Wechselt dein Shop die Seiten ohne Neuladen, teilst du dem Chat mit barry.updateChat(...) mit, wo die Person gerade ist. Siehe Product chat in deinem Shop installieren.

Popups

Popups mit Auslöser öffnen sich von selbst, ganz ohne Code. Um eines über einen eigenen Button oder Link zu öffnen, nimm seine ID aus dem Popup-Editor:

barry.openPopup("POPUP_ID");
barry.closePopup();

// In Shops ohne Neuladen zwischen Seiten: sag, was gerade angesehen wird
barry.setPopupContext({ productId: "PRODUCT_ID", cartState: "nonempty" });

Mehr dazu in Popup erstellen.

In den Warenkorb legen

Quiz, Suche und Chat legen alle über denselben Helfer in den Warenkorb. Du kannst ihn auch nutzen, auf Shopify, WooCommerce, CCV Shop und Magento:

const result = await barry.cart.add([{ reference: "VARIANT_ID", quantity: 1 }]);
// { success: true, skipped: [] } oder failure: "soldOut" | "error"

barry.cart.reveal(); // den Warenkorb-Drawer öffnen oder zur Warenkorbseite gehen

reference ist das, was der Warenkorb deines Shops erwartet: auf Shopify die Varianten-ID, auf CCV Shop und Magento die Produkt-ID (auf Magento die ID der Variante eines konfigurierbaren Produkts, nicht die des Produkts selbst).

Auf Ereignisse hören

bluebarry meldet einige Momente auf der Seite, damit deine eigenen Skripte (oder deine Analyse) darauf reagieren können:

document.addEventListener("barry:cart:added", (e) => {
  console.log("In den Warenkorb gelegt", e.detail.items);
});

document.addEventListener("barry:chat:status", (e) => { /* e.detail.state */ });
document.addEventListener("barry:chat:product-click", (e) => { /* e.detail ist das Produkt */ });

barry:cart:added wird bei jedem Hinzufügen aus jeder bluebarry-Funktion ausgelöst. Ein Listener deckt also alles ab.

Wie bluebarry Besucher wiedererkennt

Das Skript setzt ein First-Party-Cookie, bb_uid, auf deiner eigenen Domain. Es enthält eine zufällige Besucher-ID und gilt zwei Jahre. Weil es auf deiner Hauptdomain liegt, teilen es alle Funktionen und alle Subdomains: Ein Quiz auf quiz.deinshop.de und die Suche auf deinshop.de sehen denselben Besucher. So landen Quiz-Antworten, Suchen, Popup-Anmeldungen, Chats und Bestellungen in einem Profil.

• Nach einem Quiz merken sich zwei weitere Cookies (bb_session und bb_advisor) dieses Quiz 30 Tage lang, damit eine spätere Bestellung ihm noch zugeordnet werden kann.
• barry.getUid() gibt die Besucher-ID zurück, falls du sie in eigenen Systemen abgleichen willst.
• Ohne Cookies funktioniert für die Kundschaft alles weiter: Quizze, Suche, Chat und Popups verhalten sich wie gewohnt. Was verloren geht, ist die Verbindung zwischen Besuchen. Jeder Seitenaufruf zählt als neuer Besucher, Antworten und Suchen ergeben kein Profil, und Bestellungen lassen sich keinem Quiz zuordnen.