FS.event-API – Senden benutzerdefinierter Ereignisdaten an Fullstory

• Einführung
• Anweisungen
• Einschränkungen und Richtlinien
• Beispiele
• „Order Completed“-Ereignisse
• Testinformationen

Einführung

Fullstory bietet dir sofortige Insights und die Möglichkeit, Suchvorgänge zu erstellen und Einblicke ohne jegliche Instrumentierung zu erhalten. Du kannst jederzeit nach Benutzer:innen suchen, die auf einen beliebigen CSS-Selektor oder Text auf deiner Website oder mobilen App geklickt oder getippt haben, um sofort Einblicke zu erhalten.

Aber vielleicht möchtest du einige benutzerdefinierte instrumentierte Ereignisse als zusätzliche Kontextebene zu deinen reichhaltigen Daten von Fullstory hinzufügen, wenn du:

• mehr Details erfassen möchtest, als durch Klick- oder Tippaktionen des:der Benutzer:in erfasst werden können,

• bereits einige wichtige Ereignisse identifiziert hast, die für dich entscheidend sind, um dein Kundenerlebnis zu verstehen,

• bereits einige Ereignisse in einer Kundendatenplattform instrumentiert hast, die du in Fullstory einbinden möchtest.

Genau wie FS.identify und FS.setUserVars, mit denen du benutzerdefinierte Benutzerdaten abrufen kannst, um weitere wertvolle Informationen über deine Benutzer:innen zu identifizieren und zu deiner Fullstory-Erfahrung hinzuzufügen, haben wir FS.event entwickelt. So kannst du deine benutzerdefinierten Ereignisdaten abrufen, um Ereignisse innerhalb einer Session zu identifizieren und ihnen mehr Kontext zu verleihen. Du kannst Client-seitig instrumentierte Ereignisse über unsere JavaScript-API an Fullstory senden, um deine Sessions zu finden und zu segmentieren.

Springe dann beim Anzeigen von Sessions direkt zum wichtigsten Teil und sieh dir die nützlichen Eigenschaften an, die du gesendet hast.

Wenn du also Client-seitige Ereignisse über unsere JavaScript-API FS.event senden möchtest, lies weiter.

Anweisungen

Mit der neuen JavaScript-API FS.event kannst du dem von Fullstory erfassten Ereignis-Stream ein benutzerdefiniertes Ereignis hinzufügen.

FS.event(eventName, eventProperties); //

Der eventName-Parameter ist ein String, der den Namen des Ereignisses enthält. Der genaue Ereignisname kann über die OmniSearch-Funktionen von Fullstory gesucht werden.

Der eventProperties-Parameter ist ein JSON-Objekt, das zusätzliche Informationen zum Ereignis enthält. Die Eigenschaften, die für jedes Ereignis relevant sind, können stark variieren. Ereigniseigenschaften können über OmniSearch gesucht werden.

eventName und eventProperties haben spezifische Formatierungs- und Inhaltsanforderungen. Diese Anforderungen sind in den Client-API-Dokumenten detailliert beschrieben. Wenn Ereignisnamen oder ‑eigenschaften diese Anforderungen nicht erfüllen, werden sie nicht in Fullstory erfasst.

Füge den FS.event-Code zu deiner Website hinzu, führe ein Redeployment durch und folge dann den Testinformationen unten, um deine benutzerdefinierten Ereignisse in Fullstory anzuzeigen!

Einschränkungen und Richtlinien

Bitte lies die Dokumente zum Client-API-Format, um einen umfassenden Überblick über alle Einschränkungen und Richtlinien für das Senden benutzerdefinierter Daten an Fullstory zu erhalten.

Namen von benutzerdefinierten Ereignissen dürfen aus Strings mit maximal 250 Zeichen bestehen. Für benutzerdefinierte Ereignisnamen können beliebige Zeichen oder Symbole verwendet werden (es gibt kein bestimmtes Set an Zeichen, das verwendet werden muss). Benutzerdefinierte Ereignisse mit Namen, die länger als 250 Zeichen sind, werden jedoch abgelehnt. Benutzerdefinierte Ereignisnamen mit leeren Strings ("") werden ebenfalls abgelehnt.

Fullstory kann derzeit keine Ereigniseigenschaften erfassen, die Arrays von Objekten sind (mit Ausnahme der Eigenschaft „Products“ in „Order Completed“-Ereignissen, weitere Details unten). Diese Werte werden ignoriert, bis sie zu einem späteren Zeitpunkt unterstützt werden. 

Alle Eigenschaften sollten gemäß den Anforderungen in den Dokumenten zum Client-API-Format mit einem Typensuffix versehen werden. Wenn eine Eigenschaft kein Typensuffix hat, versuchen wir, den Typ abzuleiten. Die Ableitung des Typs ist als Fallback gedacht. Wir empfehlen, dass alle benutzerdefinierten Eigenschaften, die an Fullstory gesendet werden, ein Typensuffix enthalten.

Fullstory indiziert alle benutzerdefinierten Ereignisnamen oder Eigenschaften, die du für deine Anwendungsfälle benötigst, und macht sie für die Suche verfügbar. Wenn du dein Ereignisbenennungs- und Payload-Schema jedoch noch entwirfst, empfehlen wir die Übernahme des Segment-Ereignisschemas.

• Wir planen, Funktionen und Analysen für Ereignisse, die dieser Spezifikation entsprechen, zu veröffentlichen. Ein Beispiel für diese Analyse (eine, die wir derzeit unterstützen) ist die Nachverfolgung des Dollarwerts von „Order Completed“-Ereignissen zum Zweck der Umsatzzuordnung. Weitere Details unten. 

• Wenn du ein Datenformat hast, das sich vom Schema des Segments unterscheidet, akzeptiert und indiziert Fullstory auch diese Daten und macht sie durchsuchbar. Einige zukünftige Suchfunktionen könnten jedoch möglicherweise eingeschränkter sein.

Beispiele

✅ Diese zwei Beispiele für Ereignisse werden von Fullstory akzeptiert.

FS.event('Product Added', {
  cart_id_str: '130983678493',
  product_id_str: '798ith22928347',
  sku_str: 'L-100',
  category_str: 'Clothing',
  name_str: 'Button Front Cardigan',
  brand_str: 'Bright & Bold',
  variant_str: 'Blue',
  price_real: 58.99,
  quantity_real: 1,
  coupon_str: '25OFF',
  position_int: 3,
  url_str: 'https://www.example.com/product/path',
  image_url_str: 'https://www.example.com/product/path.jpg'
});

FS.event('Subscribed', {
  uid_str: '750948353',
  plan_name_str: 'Professional',
  plan_price_real: 299,
  plan_users_int: 10,
  days_in_trial_int: 42,
  feature_packs: ['MAPS', 'DEV', 'DATA'],
});

🚫 Unten ist ein Beispiel für ein Ereignis, das ein Array von Objekten übergibt, die ignoriert werden.

FS.event('Created Fields', {
  project_id_str: '1435323',
  fields: [{
    id: 'f84th3',
    name: 'User'
  }, {
    id: 'v8e9jv4',
    name: 'Title'
  }]
});

„Order Completed“-Ereignisse

„Order Completed“-Ereignisse werden von Fullstory auf besondere Weise behandelt. Diese Ereignisse werden einer zusätzlichen Transformation unterzogen, um zukünftige Suchen basierend auf Einnahmen zu erleichtern.

Arrays von Objekten werden im Allgemeinen ignoriert. Hier besteht jedoch eine Ausnahme: In einem „Order Completed“-Ereignis werden Arrays von Objekten in der „Products“-Eigenschaft akzeptiert. Diese Ausnahme gilt nur für Client-seitige Ereignisse.

Wenn du deine „Order Completed“-Ereignisse so formatieren möchtest, dass du von zukünftigen Umsatzsuchen profitieren kannst, empfehlen wir dir, der „Order Completed“-Spezifikation des Segments zu folgen.

Es gibt drei Dinge, die wir tun, wenn wir ein „Order Completed“-Ereignis erhalten.

1. Wir teilen die Produkte in der Eigenschaft „Products“ in ein eigenes Ereignis namens „Product Purchased“ auf.

2. Um die Produkte ihrer Bestellung zuzuordnen und sie mit der Bestellung zu verbinden, in der sie gekauft wurden, kopieren wir die orderId- und checkoutId-Eigenschaften aus dem „Order Completed“-Ereignis in das „Product Purchased“-Ereignis, sofern sie verfügbar sind.

3. Um die zukünftige Umsatzzuordnung zu erleichtern, berechnen wir auch den Umsatz aus Preis- und Mengeneigenschaften, sofern beide verfügbar sind. Dies ist als eine weitere Eigenschaft namens „Revenue“ im „Product Purchased“-Ereignis festgelegt und kann in der Fullstory-App durchsucht werden.

Was bedeutet das nun für eine Fullstory-Session?

• Wenn ein „Order Completed“-Ereignis mit drei Produkten ausgelöst wird, siehst du ein „Order Completed“-Ereignis und drei „Product Purchased“-Ereignisse am selben Punkt in der Zeitachse.

Hier ist ein Beispiel für den Ereignisaufruf „Order Completed“.

FS.event('Order Completed', {
  orderId_str: '23f3er3d',
  products: [{
    productId_str: '9v87h4f8',
    price_real: 20.00,
    quantity_real: 0.75
  }, {
    productId_str: '4738b43z',
    price_real: 12.87,
    quantity_real: 6,
  }]
});

Das obige „Order Completed“-Ereignis wird in die folgenden drei Ereignisse in der Fullstory-App übersetzt.

Order Completed
{
  orderId: '23f3er3d'
}

Product Purchased
{
  orderId: '23f3er3d'
  productId: '9v87h4f8',
  price: 20.00,
  quantity: 0.75,
  revenue: 15.00
}

Product Purchased
{
  orderId: '23f3er3d'
  productId: '4738b43z',
  price: 12.87,
  quantity: 6,
  revenue: 77.22
}

Testinformationen

1. Nachdem du den FS.event-Code zu deiner Website hinzugefügt hast, führe ein Testereignis durch (z. B. ein Produkt in den Warenkorb legen oder sich für den E-Mail-Newsletter anmelden).
2. Warte bis zu 30 Minuten oder aktualisiere die Seite. 
3. Teste dann in Fullstory, ob du die von dir gesendeten Ereignisse mit Namen und Eigenschaften sehen kannst.

Um zu bestätigen, dass deine Ereignisse erfolgreich an Fullstory gesendet wurden, suche sowohl über die Suchfunktion als auch in den Ereignisfiltern nach den benutzerdefinierten Ereignissen.

Innerhalb von OmniSearch (der oberen Suchleiste) solltest du einen Abschnitt namens „API-Ereignisse“ sehen (die Bezeichnungen „Checkout Error“, „Order Completed“ etc. sind nur Beispiele).

In der Suche steht dir außerdem ein neuer Ereignisfilter mit dem Namen „Benutzerdefiniertes Ereignis“ zur Verfügung:

Wenn du Eigenschaften mit diesen Ereignissen übermittelt hast, klicke auf das Symbol „Ereignis verfeinern nach …“, um basierend auf Eigenschaften weitere Filter einzufügen und die Suche zu erweitern.

Bei der Wiedergabe kannst du die Ereignisse als Anmerkung zur Wiedergabe sehen:

Und in der Ereignisliste rechts neben der Wiedergabe kannst du noch weiter verfeinern, um die mit den Ereignissen verknüpften Eigenschaften anzuzeigen:

Sieh dir abschließend auch Einstellungen > Datenmanagement > Ereignisse an, um kleinere Anpassungen vorzunehmen. Du kannst bei Bedarf bestimmte Eigenschaften oder Ereignisse archivieren (wenn du einen Fehler gemacht hast oder dieses Ereignis nicht mehr in Fullstory sehen willst). Nach der Archivierung findest du diese Ereignisse, Eigenschaften usw. im Drop-down-Menü auf jeder Folgeseite. Wenn du eine Archivierung aufheben möchtest, klicke einfach auf die vertikalen Punkte oder auf das Ordnersymbol am Ende der Zeile des jeweiligen Objekts. Im Laufe der Zeit, wenn dein Retention-Zeitraum für Produktanalysen abläuft, werden ältere Ereignisse, die du nicht mehr verwendest, nicht mehr in dieser Liste angezeigt. Insbesondere werden API-definierte Ereignisse aus deiner Ereignistabelle verschwinden, nachdem das Fenster verstrichen ist. Die Ausnahme wäre, wenn ein API-definiertes Ereignis mit demselben Namen wie das zuvor abgelaufene Ereignis erneut erfasst wird. In diesem Fall würde es erneut in der Ereignistabelle erscheinen. Benutzerdefinierte Ereignisse bleiben immer in der Tabelle, auch nachdem das Zeitfenster verstrichen ist.

Du kannst dir auch die API-Fehlertabelle ansehen, um Fehler zu beheben, wenn du Probleme mit deinen benutzerdefinierten Ereignissen hast. Sieh dir unsere Ressourcen zur Fehlerbehebung an, um Informationen zu den angezeigten Fehlern zu erhalten.