Transformation erstellen

Mit Braze Datentransformation können Sie Webhook-Integrationen erstellen und verwalten, um den Datenfluss von externen Plattformen in Braze zu automatisieren. Diese Webhook-Integrationen können dann noch leistungsfähigere Anwendungsfälle im Marketing unterstützen. Sie können Ihre Datentransformation aus dem Standardcode erstellen oder unsere spezielle Bibliothek mit Templates verwenden, um Ihnen den Einstieg in bestimmte externe Plattformen zu erleichtern.

Voraussetzungen

1. Schritt: Quellplattform identifizieren

Identifizieren Sie eine externe Plattform, die Sie mit Braze verbinden möchten, und überprüfen Sie, ob die Plattform Webhooks unterstützt. Diese Einstellungen werden manchmal auch als „API-Benachrichtigungen“ oder „Anfragen für Webdienste“ bezeichnet.

Im Folgenden finden Sie ein Beispiel für einen Typeform-Webhook, der durch Anmeldung bei der Plattform konfiguriert werden kann:

2. Schritt: Transformation erstellen

Gehen Sie im Braze Dashboard zu Dateneinstellungen > Datenumwandlung.

Wählen Sie Transformation erstellen, um Ihre Transformation zu benennen, und wählen Sie dann Ihre Bearbeitungserfahrung.

Wählen Sie Template verwenden, um eine Template-Bibliothek zu durchsuchen, die auch Anwendungsfälle der Datentransformation enthält. Oder wählen Sie Von Grund auf neu, um eine Standard-Codevorlage zu laden.

Wenn Sie bei Null anfangen, wählen Sie ein Ziel für Ihre Transformation. Sie können trotzdem eine Codevorlage aus der Vorlagenbibliothek einfügen.

Hinweis

Möchten Sie weitere Vorlagen oder Ziele anfordern? Ziehen Sie in Erwägung, eine Produktbewertung zu hinterlassen.

Nachdem Sie Ihre Transformation erstellt haben, sehen Sie die Detailansicht der Transformation. Hier können Sie unter Webhook-Details den zuletzt empfangenen Webhook für diese Transformation einsehen und unter Transformationscode ein Feld für die Eingabe Ihres Transformationscodes.

Erfassen Sie Ihre Webhook-URL zur Verwendung im nächsten Schritt.

3. Schritt: Test-Webhook senden (empfohlen)

Dieser Schritt ist optional, aber wir empfehlen, einen Test-Webhook von Ihrer Quellplattform an Ihre neu erstellte Transformation zu senden.

1. Kopieren Sie die URL aus Ihrer Transformation.
2. Suchen Sie in Ihrer Quellplattform nach einer „Test senden“-Funktion, um einen Beispiel-Webhook zu generieren, der an diese URL gesendet wird.
   • Wenn Ihre Quellplattform nach einem Anfragetyp fragt, wählen Sie POST.
   • Wenn Ihre Quellplattform Authentifizierungsoptionen bietet, wählen Sie No authentication.
   • Wenn Ihre Quellplattform nach Geheimnissen fragt, wählen Sie No secrets.
3. Aktualisieren Sie Ihre Seite im Braze-Dashboard, um zu sehen, ob der Webhook empfangen wurde. Wenn er empfangen wurde, sollten Sie unter Most recent webhook eine Webhook-Nutzlast sehen.

So sieht es bei Typeform aus:

Hinweis

Braze Datentransformation unterstützt möglicherweise noch keine externen Plattformen, die eine spezielle Überprüfung oder Authentifizierung für Webhooks erfordern. Wenn Sie diese Art von Plattform mit Braze Datentransformation nutzen möchten, sollten Sie ein Produktfeedback hinterlassen.

4. Schritt: Transformationscode schreiben

Wenn Sie wenig bis gar keine Erfahrung mit JavaScript-Code haben oder detailliertere Anweisungen bevorzugen, folgen Sie dem Tab Anfänger – POST: Nutzer:innen tracken oder Anfänger – PUT: Mehrere Katalogartikel aktualisieren zum Schreiben Ihres Transformationscodes.

Wenn Sie Entwickler:in sind oder über umfangreiche Erfahrung mit JavaScript-Code verfügen, folgen Sie dem Tab Fortgeschritten – POST: Nutzer:innen tracken für übergeordnete Anweisungen zum Schreiben Ihres Transformationscodes.

Tipp

Um Transformationscode mit KI zu generieren, wählen Sie Code with Operator über dem Transformationscode-Editor. Dazu muss ein Webhook an Ihre Transformation gesendet worden sein. Um stattdessen mit einem vorgefertigten Template zu beginnen, wählen Sie Insert Template. Beispiel-Prompts finden Sie unter Datentransformationscode generieren.

Code with Operator ist nur verfügbar, wenn Operator für Ihr Konto aktiviert ist. Wenn Sie diese Option nicht sehen, wenden Sie sich an Ihren Account Manager.

• anfänger – nutzer:innen tracken
• anfänger – katalogartikel aktualisieren
• fortgeschritten – nutzer:innen tracken

Schreiben Sie hier den Transformationscode, um zu definieren, wie verschiedene Webhook-Werte auf Braze-Nutzerprofile abgebildet werden.

1. Neue Transformationen haben dieses Standard-Template im Abschnitt Transformation Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// Here, we will define a variable, "brazecall", to build up a `/users/track` request
// Everything from the incoming webhook is accessible via the special variable "payload"
// So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z

let brazecall = {
  "attributes": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "attribute_1": payload.attribute_1
    }
  ],
  "events": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "name": payload.event_1,
      "time": new Date(),
      "properties": {
        "property_1": payload.event_1.property_1
      }
    }
  ],
  "purchases": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "product_id": payload.product_id,
      "currency": payload.currency,
      "price": payload.price,
      "quantity": payload.quantity,
      "time": payload.timestamp,
      "properties": {
        "property_1": payload.purchase_1.property_1
      }
    }
  ]
};

// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

2. Um angepasste Attribute, angepasste Events und Käufe in Ihre Transformationsaufrufe einzubeziehen, fahren Sie mit Schritt 3 fort. Andernfalls löschen Sie die Abschnitte, die Sie nicht benötigen.
   
   
3. Für jedes Attribut-, Event- und Kauf-Objekt ist ein Nutzer:innen-Bezeichner erforderlich, entweder ein external_id, user_alias, braze_id, email oder phone. Suchen Sie den Nutzer:innen-Bezeichner in der Nutzlast des eingehenden Webhooks und fügen Sie diesen Wert über eine Nutzlastzeile als Template in Ihren Transformationscode ein. Verwenden Sie die Punktnotation, um auf die Eigenschaften von Nutzlastobjekten zuzugreifen.
   
   
4. Finden Sie die Webhook-Werte, die Sie als Attribute, Events oder Käufe darstellen möchten, und erstellen Sie ein Template für diese Werte in Ihrem Transformationscode über eine Nutzlastzeile. Verwenden Sie die Punktnotation, um auf die Eigenschaften von Nutzlastobjekten zuzugreifen.
   
   
5. Prüfen Sie für jedes Attribut-, Event- und Kauf-Objekt den Wert _update_existing_only. Setzen Sie diesen auf false, wenn Sie möchten, dass die Transformation neue Nutzer:innen erstellt, die möglicherweise noch nicht existieren. Belassen Sie den Wert auf true, um nur bestehende Profile zu aktualisieren.
   
   
6. Klicken Sie auf Validate, um eine Vorschau der Ausgabe Ihres Codes zu erhalten und zu prüfen, ob es sich um eine akzeptable /users/track-Anfrage handelt.
   
   
7. Aktivieren Sie Ihre Transformation. Wenn Sie weitere Hilfe zu Ihrem Code benötigen, bevor Sie ihn aktivieren, wenden Sie sich an Ihren Braze Account Manager.
   
   
8. Lassen Sie Ihre Quellplattform mit dem Senden von Webhooks beginnen. Ihr Transformationscode wird für jeden eingehenden Webhook ausgeführt, und die Nutzerprofile werden aktualisiert.

Ihre Webhook-Integration ist nun abgeschlossen!

Hier können Sie Transformationscode schreiben, um zu definieren, wie Sie verschiedene Webhook-Werte auf Updates von Braze-Katalogartikeln abbilden möchten.

1. Neue Transformationen enthalten dieses Standard-Template im Abschnitt Transformation Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// This is a default template that you can use as a starting point
// Feel free to delete this entirely to start from scratch, or to edit specific components

// First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
// Everything from the incoming webhook is accessible via the special variable "payload"
// As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z

let brazecall = {
  // For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
  // This variable is used to specify the catalog name which would otherwise go in the request URL
  "catalog_name": "catalog_name",

  // After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
  // Documentation for the destination endpoint: https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
  "items": [
    {
      "id": payload.item_id_1,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_2,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_3,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    }
  ]
};

// After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;

2. Transformationen für /catalogs-Ziele erfordern einen catalog_name, um den spezifischen Katalog zu definieren, der aktualisiert werden soll. Sie können dieses Feld fest codieren oder das Feld über eine Nutzlastzeile mit einem Webhook-Feld als Template einfügen. Verwenden Sie die Punktnotation, um auf die Eigenschaften von Nutzlastobjekten zuzugreifen.
   
   
3. Definieren Sie die Artikel, die Sie im Katalog aktualisieren möchten, mit den id-Feldern im Artikel-Array. Sie können diese Felder fest codieren oder ein Webhook-Feld über eine Nutzlastzeile als Template einfügen.
   
   Beachten Sie, dass catalog_column ein Platzhalterwert ist. Stellen Sie sicher, dass Artikelobjekte nur Felder enthalten, die im Katalog vorhanden sind.
   
   
4. Wählen Sie Validate, um eine Vorschau der Ausgabe Ihres Codes zu erhalten und zu prüfen, ob es sich um eine akzeptable Anfrage für den Endpunkt „Mehrere Katalogartikel aktualisieren“ handelt.
   
   
5. Aktivieren Sie Ihre Transformation. Wenn Sie weitere Hilfe zu Ihrem Code benötigen, bevor Sie ihn aktivieren, wenden Sie sich an Ihren Braze Account Manager.
   
   
6. Vergewissern Sie sich, ob Ihre Quellplattform über eine Einstellung zum Senden von Webhooks verfügt. Ihr Transformationscode wird für jeden eingehenden Webhook ausgeführt, und die Katalogartikel werden aktualisiert.

Ihre Webhook-Integration ist nun abgeschlossen!

In diesem Schritt transformieren Sie die Webhook-Nutzlast von der Quellplattform in einen Rückgabewert für ein JavaScript-Objekt. Dieser Rückgabewert muss dem Format des Anfragekörpers für den /users/track-Endpunkt entsprechen:

• Der Transformationscode wird in der Programmiersprache JavaScript akzeptiert. Jeder Standard-JavaScript-Kontrollfluss, wie z. B. die if/else-Logik, wird unterstützt.
• Der Transformationscode greift über die Variable payload auf den Anfragekörper des Webhooks zu. Diese Variable ist ein Objekt, das durch das Parsen des JSON-Anfragekörpers erstellt wird.
• Alle Features, die in unserem /users/track-Endpunkt unterstützt werden, werden unterstützt, einschließlich:
  • Nutzer:innen-Attribut-Objekte, Event-Objekte und Kauf-Objekte
  • Verschachtelte Attribute und verschachtelte Eigenschaften von angepassten Events
  • Updates für Abo-Gruppen
  • E-Mail-Adresse als Bezeichner

Wählen Sie Validate, um eine Vorschau der Ausgabe Ihres Codes zu erhalten und zu prüfen, ob es sich um eine akzeptable /users/track-Anfrage handelt.

Hinweis

Externe Netzwerkanfragen, Bibliotheken von Drittanbietern und Webhooks, die nicht im JSON-Format vorliegen, werden derzeit nicht unterstützt.

5. Schritt: Transformation überwachen

Nachdem Sie Ihre Transformation aktiviert haben, finden Sie in den Analytics auf der Hauptseite Transformations eine Zusammenfassung der Performance.

• Incoming Requests: Dies ist die Anzahl der Webhooks, die unter der URL dieser Transformation empfangen wurden. Wenn die eingehenden Anfragen 0 sind, hat Ihre Quellplattform keine Webhooks übermittelt, oder die Verbindung kann nicht hergestellt werden.
• Deliveries: Nach dem Empfang eingehender Anfragen wendet die Datentransformation Ihren Transformationscode an, um die Daten an das ausgewählte Braze-Ziel zu senden.

Es ist ein gutes Ziel, dass 100 % der eingehenden Anfragen zu Zustellungen führen. Die Anzahl der Zustellungen wird niemals die Anzahl der eingehenden Anfragen übersteigen.

Fehlerbehebung

Für eine detailliertere Überwachung und Fehlerbehebung finden Sie auf der Seite Logs spezifische Protokolle, in denen die letzten 1.000 eingehenden Anfragen an alle Transformationen in Ihren Workspaces protokolliert werden. Sie können jedes Protokoll auswählen, um den eingehenden Anfragekörper, die Transformationsausgabe und den Antwortkörper des Transformationsziels anzuzeigen.

Wenn es keine Zustellungen gibt, überprüfen Sie Ihren Transformationscode auf Syntaxfehler und stellen Sie sicher, dass der Code kompiliert werden kann. Prüfen Sie dann, ob die Ausgabe eine gültige Zielanfrage ist.

Zustellungen, die geringer sind als die Anzahl der eingehenden Anfragen, zeigen an, dass zumindest einige Webhooks erfolgreich zugestellt wurden. Schauen Sie in den Transformationsprotokollen nach Beispielfehlern und prüfen Sie, ob die Transformationsausgabe den Erwartungen entspricht. Es ist möglich, dass Ihr Transformationscode nicht alle Varianten der empfangenen Webhooks berücksichtigt.