REST-API-Dokumentation

Unsere Entwicklerdokumente enthalten umfassende Anweisungen, Code-Beispiele, FAQs und mehr zur REST- und JS-API.

Benutze sie, um mehr über folgende Themen zu erfahren:

  • Integration von Bunchbox mit deinem CMS
  • Erstellen von benutzerdefinierten Zielgruppen und Ereignissen
  • Bedingtes Aktivieren von Experimenten
  • Abruf von Daten in internen Reports und mehr.

Bunchbox nutzt eine JavaScript-Datei auf deiner Seite, um diverse Funktionen bereitzustellen. Diese Datei umfasst die gesamte Logik und zudem wichtige Informationen, die du über die App in deinem Account einrichtest.

Das Skript wird über ein CDN (Content-Delivery-Network) zur Verfügung gestellt und garantiert damit eine nahe Position zum Webseitenbesucher und somit eine Verbesserung der Konnektivität.

Das Skript-Tag zu deinem Account findest du in den Einstellungen deines Accounts.

Tipp
Bunchbox empfiehlt, das Skript synchron und so hoch wie möglich im Kopfbereich der Seite zu platzieren. Dies dient nicht nur der schnellstmöglichen Ausführung, sondern vermeidet visuelle Verzögerungen, welche sich negativ auf das Verhalten des Webseitenbesuchers auswirken können. Bunchbox sollte zudem nicht dynamisch über JavaScript in der Seite platziert werden, da diese von Browsern implizit asynchron behandelt wird. Dies umfasst auch die Nutzung von Drittanbieter-Diensten wie z.B. dem Google Tag Manager.

!DOCTYPE html>
<html>
<head>
  <title>Bunchbox implementation sample</title>
  <script src="//cdn.bunchbox.co/4aa7bb5c5616ee6459a19734.min.js"></script>
</head>

<body>
The content of the document......
</body>
</html>

Schnittstelle

Globale Variablen

<!DOCTYPE html>
<html>
<head>
  <title>Bunchbox implementation sample</title>
  <script>
    window._bb = window._bb || [];
    window._bb.push([command, value]);
  </script>
  <script src="//cdn.bunchbox.co/4aa7bb5c5616ee6459a19734.min.js"></script>
</head>

<body>
The content of the document......

<script>
  window._bb = window._bb || [];
  window._bb.push([another_command, value]);
</script>
</body>
</html>

Bunchbox vermeidet unnötige Variablen am globalen Namespace zu definieren. Es werden ausschließlich die Variablen _bb_helpers und _bb global definiert. Letzteres dient dir als Schnittstelle.

Du kannst diese Schnittstelle – abhängig vom Befehl – vor, während oder nach der Ausführung von Bunchbox verwenden.

Das _bb Objekt definiert die push Methode.

_bb.push(array_with_commands...);

Die Methode erwartet mindestens ein Array, welches den Befehl beschreibt.

Benutzerdefinierte Attribute

Besucher-Attribute

window._bb = window._bb || [];
window._bb.push(
    ['attribute', 'source', 'social'],
    ['attribute', 'hasNewsletter', true]
);

window._bb.push(['attribute', type, [value]])

Stehen dir Besucher-Attribute zur Verfügung, kannst du diese Bunchbox vor der Ausführung übergeben. Die von dir zur Verfügung gestellten Attribute kannst du z.B. für Targeting-Bedingungen nutzen.

  • type der Name des Attributes
  • value (optional) der Wert des Attributes

Du kannst den aktuell gesetzten Wert ermitteln, indem du nur type übergibst. Wie z.B. var source = window._bb.push(['attribute', 'source']);

Ecommerce-Attribute

window._bb = window._bb || [];
window._bb.push(
    ['ecommerce', 'orderSize', 99.99],
    ['ecommerce', 'productIds', ['id1', 'id2']],
    ['ecommerce', 'orderId', '48b7db13-a8c9-44c1-be18-5ea46e35c01f']
);

window._bb.push(['ecommerce', [type], [value]])

Um Erfolgsmetriken wie z.B. Revenue-Per-Visitor im Report einsehen zu können, musst du uns auf Seiten, auf denen von dir definierte Ziele erreicht werden können, bestimmte Werte übergeben. Jeder Conversion kann ein Kaufwert orderSize, die ID der Bestellung orderId und IDs gekaufter Produkte productIds zugeordnet werden.

  • type der Name des Ecommerce-Wertes
  • value (optional) der Ecommerce-Wert

Du kannst den aktuell gesetzten Wert ermitteln, indem du nur type übergibst. Wie z.B. var orderSize = window._bb.push(['ecommerce', 'orderId']);

Manuelle Experiment-Aktivierung

window._bb = window._bb || [];
window._bb.push(['activate experiment', '4aa7f5d0a7a7bad33b439b9a']);

window._bb.push(['activate experiment', experimentId, [stepIndex]])

Hast du ein Experiment erstellt, welches keine Targeting-Bedingungen besitzt, kannst du dieses manuell aktivieren.

  • experimentId die ID des Experiments, welches du aktivieren möchtest
  • stepIndex (optional) falls das Experiment mehrere Steps besitzt, kannst du den Index des Steps übergeben

Tracking von Ereignis-Zielen

window._bb = window._bb || [];
window._bb.push(['track event goal', '4aa7f5d0a7a7bad33b439b9a', 'goalId']);

window._bb.push(['track event goal', [experimentId], goalId])

Besitzt dein Experiment ein Ereignis-Ziel, kannst du dies mit diesem Befehl tracken. Die ID des Experiments ist hierbei optional. Lässt du diese weg, werden alle aktiven Experimente in Betracht gezogen. Besitzen mehrere Experimente ein Ereignis-Ziel mit der entsprechenden goalId, werden für alle zutreffenden Ziele eine Conversion getracked.

  • experimentId (optional) die ID des Experiments
  • goalId die ID des Ereignis-Ziels
window._bb = window._bb || [];
var link = window._bb.push(['cross domain link']);

// auf einer weiteren Domain

window._bb.push(['cross domain link', link]);

window._bb.push(['cross domain link', [linkObject]])

Bunchbox bietet die Möglichkeit, die bestehenden Test-Teilnahmen eines Besuchers als Link-Objekt zu serialisieren. Diesen Link kannst du anschließend auf eine weitere Domain manuell übertragen, um so beide Domains unidirektional zu verlinken. Ein Link hat eine Lebensdauer von 30 Sekunden.

Nach Empfang eines Link-Objektes auf der zweiten Domain, kannst du den Link Bunchbox übergeben.

  • linkObject (optional) ein Link-Objekt

Abgesicherter Modus

window._bb = window._bb || [];
window._bb.push(['safe mode', true]);

window._bb.push(['safe mode', isSafeModeEnabled])

Möchte man auf bestimmten Seiten die Ausführung von Varianten – unabhängig vom Targeting – verhindern, kann dies über den Befehl safe mode sichergestellt werden. Dieser Befehl führt dazu, dass keine Experimente evaluiert bzw. ausgeführt werden. Es kann somit zu keinen DOM-Manipulationen seitens der Experimente kommen. Experiment-Ziele werden hingegen weiterhin ausgewertet.

  • isSafeModeEnabled ein Boolean, mit dem man den abgesicherten Modus aktivieren bzw. deaktivieren kann

Status-Abfrage

window._bb = window._bb || [];
window._bb.push([
    'get state',
    function(state) {
        // read from state ...
    }
]);

window._bb.push(['get state', callback])

Um den Status der aktuellen Evaluierung abfragen zu können, kann der Befehl get state verwendet werden. Dieser Befehl kann zu jedem Zeitpunkt ausgeführt werden. Die übergebene Callback-Funktion wird ausgeführt, sobald die Evaluierung abgeschlossen ist. Die Evaluierung umfasst neben der Auswertung von User- und Tracking-Filtern, auch die der Experiment-Targeting-Bedingungen, Varianten und Zielen. Sobald die Ausführung abgeschlossen ist, wird die angegebene Callback-Funktion ausgeführt. Als ersten Parameter erhält diese ein JavaScript-Objekt. Dieses Objekt enthält neben den Ergebnissen der Tracking- und User-Filter, auch eine Übersicht über alle zuvor definierten Benutzer-Attribute und eine Liste von eventuell ausgeführten Experimenten.

  • callback eine Callback-Funktion, mit welcher dem Ausführenden Status-Informationen angeboten werden
{
    accountId: '4b447121b2d3c8851f61a62a',
    userId: '4b447134b2d3c8851f61a62c',
    isUserExcludedByUserFilter: false,
    isUserExcludedByTrackingFilter: false,
    customAttributes: {
        page_type: 'pdp',
        hasNewsletter: false
    },
    activeExperiments: [
        {
            experimentId: '4b44660d0206844801d8f76a',
            experimentName: 'LP Button Test',
            variantId: '4b44660d0206844801d8f783',
            variantName: 'Button Position Left',
            event: 'bb_experiment_lp_button_test_button_position_left'
        }
    ]
}

Flackern verhindern

window._bb = window._bb || [];
window._bb.push(['prevent flickering']);

window._bb.push(['prevent flickering', options])

Es gibt einige Situationen, in denen das Bunchbox JavaScript asynchron ausgeführt wird. In diesen Fällen kann eine Originalvariante sichtbar sein, bevor visuelle Änderungen durch die tatsächlich asynchron ausgeführte Variante vorgenommen werden. Dieser Befehl veranlasst das JavaScript, dem Dokumentelement eine CSS-Klasse hinzuzufügen. Die CSS-Klasse wird verwendet, um die Deckkraft der gesamten Seite auf Null zu setzen. Nach Ausführung des JavaScripts, wird die Klasse wieder entfernt, so dass der Besucher durch springende Elemente nicht beeinträchtigt wird.

Sofern nicht anders konfiguriert, ist bb-async-hide der erwartete Klassenname. Du solltest sicherstellen, dass diese Klasse definiert ist, bevor das Bunchbox-JavaScript ausgeführt wird.

Wenn du bereits eine Klasse hast, die es dir erlaubt, die Deckkraft auf Null zu setzen, kannst du uns dies mit { className: 'my-custom-hide-class' } als zweiten Parameter mitteilen.

  • options ein optionales Objekt, das zur Konfiguration des Befehls verwendet wird
<!DOCTYPE html>
<html>
  <head>
    <title>Bunchbox implementation sample</title>
    <style>
      .prevent-flickering {
        opacity: 0 !important;
      }
    </style>
    <script>
      window._bb = window._bb || [];
      window._bb.push([
        'prevent flickering',
        { className: 'prevent-flickering' }
      ]);
    </script>
    <script src="//cdn.bunchbox.co/4aa7bb5c5616ee6459a19734.min.js"></script>
  </head>

  <body>
    The content of the document......
  </body>
</html>

Flackern verhindern bei asynchroner Implementierung

<!DOCTYPE html>
<html>
  <head>
    <title>Bunchbox implementation sample</title>
    <style>
      .bb-async-hide {
        opacity: 0 !important;
      }
    </style>
    <script>
      /**
       * @param {Window} b The global object.
       * @param {HTMLDocument} e The document.
       * @param {HTMLHtmlElement} c The html element.
       * @param {string} d The name of property of the global Bunchbox object.
       * @param {string} h The account id used to load the Bunchbox script.
       * @param {string} g The class name used to hide the page
       * @param {number} a The maximium timeout in ms used as fallback
       */
      (function(b, e, c, d, h, g, a) {
        b[d] = b[d] || [];
        var f = b[d].show = function() {
          c.className = c.className.replace(RegExp(" ?" + g), "");
          f = b[d].show = function() {};
        };
        b.setTimeout(function() {
          f();
        }, a);
        c.className += " " + g;
        a = e.createElement("script");
        a.async = !0;
        a.src = "//cdn.bunchbox.co/" + h + ".min.js";
        a.onerror = function() {
          f();
        };
        (e.head || e.getElementsByTagName("head")[0]).appendChild(a);
      })(window, document, document.documentElement, "_bb", "539dd741b822cc631f000003", "bb-async-hide", 2000);
    </script>
  </head>
  <body>
    The content of the document......
  </body>
</html>

That’s it. Jetzt hast du alle Funktionen, um Bunchbox zu nutzen.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren.Erfahren Sie, wie Ihre Kommentardaten verarbeitet werden