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

Schritt 1: Eine Quellplattform identifizieren

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

Im Folgenden sehen Sie ein Beispiel für einen Typeform-Webhook, den Sie konfigurieren können, indem Sie sich auf der Plattform von Typeform anmelden:

Schritt 2: Eine Transformation erstellen

Gehen Sie im Braze-Dashboard zu Dateneinstellungen > Datentransformation.

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 ein Standard-Code-Template zu laden.

Wenn Sie bei Null anfangen, wählen Sie ein Ziel für Ihre Transformation. Sie können trotzdem ein Code-Template aus der Template-Bibliothek einfügen.

Hinweis

Sie wünschen sich additional templates or destinations? Hinterlassen Sie gerne Produktfeedback.

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 Ihren Transformationscode schreiben.

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

Schritt 3: Einen Test-Webhook senden (empfohlen)

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

1. Kopieren Sie die URL Ihrer Transformation.
2. Suchen Sie in Ihrer Quellplattform nach einer Funktion wie „Send Test“, um einen Beispiel-Webhook zu erzeugen und an diese URL zu senden.
   • Wenn Ihre Quellplattform nach einem Anfragetyp fragt, wählen Sie POST aus.
   • Wenn Ihre Quellplattform Authentifizierungsoptionen anbietet, wählen Sie Keine Authentifizierung aus.
   • Wenn Ihre Quellplattform nach Secrets fragt, wählen Sie Keine Secrets aus.
3. Aktualisieren Sie Ihre Seite im Braze-Dashboard, um zu prüfen, ob der Webhook empfangen wurde. Wenn er empfangen wurde, sollten Sie unter Letzter Webhook einen Webhook-Payload sehen.

So sieht das für Typeform aus:

Hinweis

Braze Data Transformation unterstützt möglicherweise noch keine externen Plattformen, die eine spezielle Verifizierung oder Authentifizierung für Webhooks erfordern. Sie wünschen sich webhook authentication for external platforms? Hinterlassen Sie gerne Produktfeedback.

Schritt 4: Transformationscode schreiben

Wenn Sie wenig oder keine Erfahrung mit JavaScript-Code haben oder ausführlichere Anweisungen bevorzugen, folgen Sie dem Tab Beginner - POST: Track users oder Beginner - PUT: Update multiple catalog items, um Ihren Transformationscode zu schreiben.

Wenn Sie Entwickler:in sind oder viel Erfahrung mit JavaScript-Code haben, folgen Sie dem Tab Advanced - POST: Track users. Dort finden Sie allgemeine Anweisungen zum Schreiben Ihres Transformationscodes.

Tipp

Um Transformationscode mit KI zu generieren, wählen Sie im Editor für den Transformationscode Code with Operator aus. Dafür muss ein Webhook an Ihre Transformation gesendet werden. Wenn Sie stattdessen mit einem vorgefertigten Template beginnen möchten, wählen Sie Insert Template aus. Beispiel-Prompts finden Sie unter Code für Datentransformationen 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.

• beginner - track users
• beginner - update catalog items
• advanced - track users

Hier schreiben Sie Transformationscode, der festlegt, wie verschiedene Webhook-Werte Braze-Nutzerprofilen zugeordnet werden.

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

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. Wenn Sie angepasste Attribute, angepasste Events und Käufe in Ihre Transformationsaufrufe aufnehmen möchten, fahren Sie direkt mit Schritt 3 fort. Löschen Sie andernfalls die Abschnitte, die Sie nicht benötigen.
   
   
3. Jedes Attribut-, Event- und Kauf-Objekt benötigt einen Nutzer-Bezeichner: entweder external_id, user_alias, braze_id, email oder phone. Suchen Sie den Nutzer-Bezeichner im Payload des eingehenden Webhooks und fügen Sie diesen Wert über eine Payload-Zeile als Template in Ihren Transformationscode ein. Verwenden Sie die Punktnotation, um auf Eigenschaften des Payload-Objekts zuzugreifen.
   
   
4. Suchen Sie die Webhook-Werte, die Sie als Attribute, Events oder Käufe abbilden möchten, und fügen Sie diese Werte über eine Payload-Zeile als Template in Ihren Transformationscode ein. Verwenden Sie die Punktnotation, um auf Eigenschaften des Payload-Objekts zuzugreifen.
   
   
5. Prüfen Sie für jedes Attribut-, Event- und Kauf-Objekt den Wert _update_existing_only. Setzen Sie ihn auf false, wenn die Transformation neue Nutzer:innen anlegen soll, die möglicherweise noch nicht existieren. Belassen Sie ihn 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 gültige /users/track-Anfrage handelt.
   
   
7. Aktivieren Sie Ihre Transformation. Wenn Sie vor der Aktivierung weitere Hilfe zu Ihrem Code benötigen, 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 nach und nach aktualisiert.

Ihre Webhook-Integration ist jetzt abgeschlossen!

Hier können Sie Transformationscode schreiben, der festlegt, wie verschiedene Webhook-Werte Updates von Braze-Katalogartikeln zugeordnet werden sollen.

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

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 and create a new transformation, or 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: /docs/de/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 benötigen einen catalog_name, der den zu aktualisierenden Katalog festlegt. Sie können dieses Feld fest codieren oder über eine Payload-Zeile mit einem Webhook-Feld als Template befüllen. Verwenden Sie die Punktnotation, um auf Eigenschaften des Payload-Objekts zuzugreifen.
   
   
3. Legen Sie mit den id-Feldern im Array „items“ fest, welche Artikel im Katalog aktualisiert werden sollen. Sie können diese Felder fest codieren oder über eine Payload-Zeile ein Webhook-Feld als Template einfügen.
   
   Beachten Sie, dass catalog_column ein Platzhalterwert ist. Achten Sie darauf, dass Artikel-Objekte nur Felder enthalten, die im Katalog existieren.
   
   
4. Wählen Sie Validate aus, um eine Vorschau der Ausgabe Ihres Codes zu erhalten und zu prüfen, ob es sich um eine gültige Anfrage für den Endpunkt zum Aktualisieren mehrerer Katalogartikel handelt.
   
   
5. Aktivieren Sie Ihre Transformation. Wenn Sie vor der Aktivierung weitere Hilfe zu Ihrem Code benötigen, wenden Sie sich an Ihren Braze Account Manager.
   
   
6. Prüfen Sie, ob Ihre Quellplattform eine Einstellung zum Starten des Webhook-Versands hat. Ihr Transformationscode wird für jeden eingehenden Webhook ausgeführt, und die Katalogartikel werden nach und nach aktualisiert.

Ihre Webhook-Integration ist jetzt abgeschlossen!

In diesem Schritt wandeln Sie den Webhook-Payload der Quellplattform in einen JavaScript-Objekt-Rückgabewert um. Dieser Rückgabewert muss dem Format des Anfragekörpers des Endpunkts /users/track entsprechen:

• Transformations-Code wird in der Programmiersprache JavaScript akzeptiert. Jede standardmäßige JavaScript-Kontrollflussstruktur, wie z. B. if/else-Logik, wird unterstützt.
• Transformations-Code greift über die Variable payload auf den Body der Webhook-Anfrage zu. Diese Variable ist ein Objekt, das durch das Parsen des JSON-Anfrage-Bodys befüllt wird.
• Jedes Feature, das in unserem /users/track-Endpunkt unterstützt wird, wird ebenfalls unterstützt, einschließlich:
  • Nutzer:innen-Attribut-Objekte, Event-Objekte und Kauf-Objekte
  • Verschachtelte Attribute und verschachtelte angepasste Event-Eigenschaften
  • Abo-Gruppen-Aktualisierungen
  • E-Mail-Adresse als Bezeichner

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

Hinweis

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

Schritt 5: Ihre Transformation überwachen

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

• Eingehende Anfragen: Dies ist die Anzahl der Webhooks, die an der URL dieser Transformation eingegangen sind. Wenn die Anzahl der eingehenden Anfragen 0 beträgt, hat Ihre Quellplattform keine Webhooks gesendet oder die Verbindung kann nicht hergestellt werden.
• Zustellungen: Nach dem Empfang eingehender Anfragen wendet die Datentransformation Ihren Transformationscode an, um die Daten an das ausgewählte Braze-Ziel zu senden.

Idealerweise führen 100 % der eingehenden Anfragen zu Zustellungen. Die Anzahl der Zustellungen kann die Anzahl der eingehenden Anfragen nie übersteigen.

Fehlerbehebung

Für eine detailliertere Überwachung und Fehlerbehebung finden Sie auf der Seite Protokolle spezifische Protokolle. Dort werden die letzten 1.000 eingehenden Anfragen an alle Transformationen in Ihren Workspaces protokolliert. Sie können jedes Protokoll auswählen, um den Body der eingehenden Anfrage, die Ausgabe der Transformation und den Body der Antwort vom Ziel der Transformation anzuzeigen.

Wenn es keine Zustellungen gibt, überprüfen Sie Ihren Transformationscode auf Syntaxfehler und stellen Sie sicher, dass der Code kompiliert wird. Prüfen Sie anschließend, ob die Ausgabe eine gültige Anfrage an das Ziel ist.

Wenn die Anzahl der Zustellungen geringer ist als die Anzahl der eingehenden Anfragen, wurden zumindest einige Webhooks erfolgreich zugestellt. Sehen Sie sich in den Transformationsprotokollen Beispielfehler an und prüfen Sie, ob die Ausgabe der Transformation den Erwartungen entspricht. Möglicherweise berücksichtigt Ihr Transformationscode nicht alle Varianten der empfangenen Webhooks.