Integration von Attractify am Beispiel eines Blogs - Teil 1

In diesem Blogbeitrag möchten wir euch zeigen, wie man Attractify nutzen kann, um einen tieferen Einblick in das Verhalten von Lesern eines Blogposts zu bekommen. Dazu verwenden wir unseren inovex.de Blog. Unser Ziel ist es, unsere User gezielter über relevante Workshops oder Stellenangebote zu informieren.

In einem ersten Schritt wollen wir herausfinden, welche Blogartikel von welchen Usern überhaupt gelesen werden.

Schritt 1: Einrichten eines Events in Attractify

Unter der Rubrik Events kann per Klick auf das “Plus” ein neues Event hinzugefügt werden. Dazu müssen folgende Attribute gesetzt werden:

Name: Legt den Namen des Events fest und wird in der Integration als eindeutige Identifikation genutzt.

Description: Eine kurze Beschreibung des Events, damit andere Attractify-User wissen, was das Event genau erfasst.

Properties: Hier werden die Datenfelder definiert, die in der Integration gesetzt werden und später als Grundlage zur Definition von Computed Traits dienen.

Wir legen zunächst ein einfaches Event an, welches das Lesen eines Blogposts registriert. Dafür benötigen wir als property den Titel des gelesenen Blogposts als string.

Schritt 2: Erstellen eines API-Keys in Attractify

Um nun Events in Attractify zu erfassen, muss man das Event an die Attractify-API schicken. Diese verarbeitet dann das Event und wertet es aus. Der Zugriff auf die Attractify-API wird über einen API-Key geregelt.

Um nun einen API-Key zu erstellen, muss zunächst ein Kanal (Channel) angelegt werden, für den dieser Key gelten soll. Da das Blog nur über die Webseite erreichbar ist, erstellen wir einen neuen Kanal mit dem Namen Website und dem Key web. Das Ergebnis sollte nun wie folgt aussehen:

Nun können wir unter API-Access einen neuen API-Token erstellen. Dies ist unter der Überschrift “Auth token for client integrations” möglich. Dazu muss nur der eben erstellte Channel Webseite ausgewählt werden.

Schritt 3: Integration in die Webseite

Für die Integration von Attractify in Webseiten ist generell auf zwei verschiedene Arten möglich:

1. Die Integration kann direkt im Quellcode der Webseite stattfinden
2. oder nachträglich über ein Script Tag geladen werden.

Während die erste Option die beste Performance und Präzision bei der Implementierung bietet entscheiden wir uns in diesem Blogeintrag für den zweiten Weg, da so keine Änderungen des Seiteninhalts notwendig sind. So kann Attractify auch in Projekten eingesetzt werden, in denen die Webseite von einem anderen Team verwaltet wird.

Dazu laden wir zunächst das Attractify SDK als Script im Head-Bereich des DOMs.

1
2
3
4

let script = document.createElement("script");
script.src = "https://cdn.attractify.io/sdk/v1.js";
script.type = "text/javascript";
document.querySelector("head").appendChild(script);

Wenn das SDK erfolgreich geladen wurde, initialisieren wir Attractify mit dem API-Key.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

let attractify = {};

let script = document.createElement("script");
script.src = "https://cdn.attractify.io/sdk/v1.js";
script.type = "text/javascript";
script.async = true;
script.onload = () => {
  attractify = new Attractify("web-foobartoken");
};
document.querySelector("head").appendChild(script);

Schritt 4: Leseverhalten tracken

Um das Leseverhalten sinnvoll zu tracken, müssen wir zunächst für uns definieren, wann ein Blogpost als gelesen gilt. Dafür kommen verschiedene Kriterien in Frage. Beispielsweise kann die Verweildauer des Users auf der Seite als Indikation dienen. Jedoch sagt diese nichts darüber aus, was der User auf der Seite macht. Ein anderes Kriterium ist das Scrollverhalten. Wird die Seite bis zum Ende, oder einem von uns definierten Punkt, durchgescrollt, hat der User den Seiteninhalt zumindest einmal ganz gesehen. Für uns soll zunächst das Scrollverhalten ausreichen. Weitere Optimierungen können später vorgenommen werden, diese sind aber sehr stark von der individuellen Situation abhängig und nur schwer auf andere Anwendungsfälle übertragbar.

Statt das Scrollverhalten des Users direkt zu beobachten, haben wir uns dafür entschieden, die Sichtbarkeit des letzten Absatzes im Viewport des Browser zu prüfen. Unsere Blogeinträge sehen ungefähr so aus:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<body>
 ...
 <div class="post__content">
   <h1 class="post__title">Title</h1>
   <p>...</p>
   <h2>Subtitle</h2>
   <p>...</p>
   <p>...</p>
   <h2>Sources</h2>
   <p></p>
 </div>
 ...
</body>

Es ist für uns hinreichend, wenn der User die Überschrift zur Quellenangabe (Sources) gesehen hat, um den Blogpost als gelesen anzusehen. Dafür erstellen wir einen IntersectionObserver. Dieser benötigt unter anderem ein root-Objekt, mit dem das Ziel verglichen werden soll, sowie einen threshold, ab dem das Ziel als intersected gilt. Wird kein root-Objekt angegeben, verwendet der IntersectionObserver den Viewport als Referenz, was genau unserem gewünschten Verhalten entspricht. Als threshold wählen wir 0.6, alle Werte über 0 wären aber für unseren Anwendungsfall möglich.

1
2
3
4
5

let options = {
  root: null,
  rootMargin: "0px",
  threshold: [0.6],
};

Sobald dieser threshold erreicht ist, führt der IntersectionObserver eine Callback-Funktion aus. In dieser Callback-Funktion bekommen wir die Einträge für unsere Zielelemente. Darin enthalten ist auch die Information zur Überschneidung von Ziel- und root-Element. Für uns ist das Attribut isIntersecting ausreichend. Trifft dies zu, soll in Attractify das Event Blog Article Read getrackt werden. Anschließend wird der Observer getrennt, um ein mehrfaches Senden des Events zu verhindern

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

let tracker = (entries, observer) => {
  entries.forEach((element) => {
    if (element.isIntersecting) {
      attractify.track("Blog Article Read", {
        title: document.querySelector(".entry-title").innerHTML,
      }).then(() => {
        observer.disconnect();
      })
    }
  });
};

Nun rufen wir die Methode track() des Attractify-Objekts auf. track() kann neben dem Namen des Events auch weitere Properties erfassen. Diese werden als zweiter Parameter in Form eines Javascript-Objekts übergeben. Bei der Erstellung des Events hatten wir eine Property namens title angelegt. Genau diese setzen wir nun auf den Titel des gelesenen Blog Posts.

Die Signatur der Methode sieht folgendermaßen aus: track(eventName, properties, context)

Der Event Name lautet Blog Article Read und die Properties bestehen aus:

1
2
3

{
  title: document.querySelector(".post__title").innerHTML
}

Zusammengefasst sieht das nun so aus:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const trackPostRead = () => {
  let options = {
    root: null,
    rootMargin: "0px",
    threshold: [0.6],
  };
  let tracker = (entries, observer) => {
    entries.forEach((element) => {
      if (element.isIntersecting) {
        attractify.track("Blog Article Read", {
          title: document.querySelector(".post__title").innerHTML,
        }).then(() => {
          observer.disconnect();
        })
      }
    });
  };
  let observer = new IntersectionObserver(tracker, options);
  let target = document.querySelectorAll(".post__content > h2");
  observer.observe(target[target.length - 1]);
};

Jetzt muss die trackPostRead() Funktion noch nach dem Laden des Attractify SDKs ausgeführt werden. Da wir hier auf DOM-Elemente zugreifen, muss auch sichergestellt werden, dass der DOM vollständig gerendert wurde. Falls nicht, setzen wir einen EventListener.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

script.onload = () => {
  attractify = new Attractify("web-foobartoken");
  // Ready state cannot be guaranteed at this point
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", () => {
      setup();
    });
  } else {
    setup();
  }

Schritt 5: Testen der Integration

Um unser Skript zu testen, ohne es live deployen zu müssen, können wir es als Userscript mit Tampermonkey (oder ähnlichen Extensions) lokal in die Webseite einbinden.

Beim Öffnen eines Blogeintrags wird nun ein Event an Attractify gesendet und im Event Log angezeigt. Diese Events können nun verwendet werden, um z. B. ein Computed Traits zu berechnen, welchen Blog Post unser User als letztes bis zum Ende gelesen hat. Und wenn es sich hierbei um einen Blog Post über z. B. Kubernetes handelt, kann man ihn direkt über kommende Webinare zu Kubernetes informieren. Dies geschieht mit unseren Aktionen in Attractify, die wir im folgenden Post genauer beschreiben.

Schritt 6: Deployment

Sind wir zufrieden mit dem Script, können wir es einfach via Script-Tag in die Seite einbinden. Mehrere Scripte werden natürlich zusammengefasst und Attractify sollte dabei auch nur einmal geladen werden. Diese Methode demonstriert, wie man einfach und ohne Hilfe einer externen Agentur, simple Trackings vornehmen kann. Möchte man eine tiefere Integration durchführen, bietet es sich an, direkt in die Seite einzugreifen.

Foto von Ilya Pavlov auf Unsplash