Zum Inhalt springen

Zero-Copy-Personalisierung mit CDI

Erfahren Sie, wie Sie Canvas-Trigger mithilfe von CDI für eine Zero-Copy-Personalisierung synchronisieren. Dieses Feature greift auf nutzerspezifische Informationen aus Ihrer Datenspeicher-Lösung zu und überträgt sie an ein Ziel-Canvas. Canvas-Schritte können optional Personalisierungsfelder enthalten, die nicht dauerhaft in Braze-Nutzerprofilen gespeichert werden.

Canvas-Trigger synchronisieren

Schnellstart

Wenn Sie bereits mit Braze CDI vertraut sind, beachten Sie: Die Einrichtung einer Canvas-Trigger-Synchronisierung folgt weitgehend dem Prozess für Nutzerdaten-CDI-Integrationen. Dabei gelten folgende Einschränkungen:

  • Nur externe IDs oder Nutzer-Aliase werden als Bezeichner unterstützt. E-Mail-Adressen und Telefonnummern werden nicht unterstützt.
  • Nur bestehende Braze-Nutzer:innen können synchronisiert werden. Neue Nutzer:innen können nicht angelegt werden.
  • properties ersetzt die Spalte payload. Dies ist ein JSON-String mit den Feldern, die Sie als Canvas-Entry-Eigenschaften für die Personalisierung verwenden möchten.

Wählen Sie zum Start beim Erstellen einer neuen Synchronisierung den Datentyp Canvas-Trigger aus.

Canvas-Trigger verwenden

Schritt 1: Datenquelle für Canvas-Trigger einrichten

Schritt 1.1: Quelltabelle in Snowflake einrichten

Sie können die Namen aus dem folgenden Beispiel verwenden oder eigene Namen für Datenbank, Schema und Tabelle wählen. Statt einer Tabelle können Sie auch eine View oder eine Materialized View verwenden.

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
     UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
     --at least one of external_id or alias_name and alias_label is required
     EXTERNAL_ID VARCHAR(16777216),
     --if using user alias, both alias_name and alias_label are required
     ALIAS_LABEL VARCHAR(16777216),
     ALIAS_NAME VARCHAR(16777216),
     PROPERTIES VARCHAR(16777216)
);

Sie können Datenbank, Schema und Tabelle beliebig benennen, die Spaltennamen sollten jedoch der vorstehenden Definition entsprechen.

  • UPDATED_AT: Der Zeitpunkt, zu dem diese Zeile aktualisiert oder der Tabelle hinzugefügt wurde. Braze synchronisiert Zeilen, deren UPDATED_AT später als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenz-Zeitstempel können erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel haben.
  • Entweder external_id oder alias_name und alias_label als Spalte für den Nutzer-Bezeichner. Diese identifizieren die Nutzer:innen, für die Sie Canvas-Nachrichten triggern möchten.
    • EXTERNAL_ID: Identifiziert die Nutzer:in, die in das Canvas eintreten soll. Dieser Wert sollte mit dem in Braze verwendeten external_id-Wert übereinstimmen.
    • ALIAS_NAME und ALIAS_LABEL: Diese Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_label.
  • PROPERTIES: Ein JSON-String mit Feldern, die in Ihrem Canvas als Personalisierungseigenschaften verfügbar sein sollen. Er sollte nutzerspezifische Informationen enthalten.
Schritt 1.2: Zugangsdaten einrichten

Richten Sie eine Rolle, ein Warehouse und eine Nutzer:in ein und erteilen Sie die erforderlichen Berechtigungen. Wenn Sie bereits Zugangsdaten aus einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden. Stellen Sie jedoch sicher, dass der Zugriff auf die Quelltabelle für Canvas-Trigger erweitert wird.

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Die Anweisung CREATE USER in diesem Beispiel gilt für die Authentifizierung per RSA-Schlüsselpaar. Für Workload Identity Federation erstellen Sie die Rolle und das Warehouse wie gezeigt und legen die Service-Nutzer:in über das Snowflake-Formular für Zugangsdaten an. Die Berechtigungen für Rolle, Warehouse und Datenbank bleiben gleich. Die Netzwerkrichtlinie im nächsten Schritt gilt weiterhin. Die Anweisung und wo Sie sie ausführen, finden Sie unter Snowflake für Workload Identity Federation konfigurieren.

Schritt 1.3: Netzwerkrichtlinien konfigurieren

Wenn Ihr Konto Netzwerkrichtlinien verwendet, setzen Sie die Braze-IPs auf die Allowlist, um die Verbindung zum CDI-Dienst zu ermöglichen. Die Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Schritt 1.1: Quelltabelle in Redshift einrichten

Sie können die Namen aus dem folgenden Beispiel verwenden oder eigene Namen für Datenbank, Schema und Tabelle wählen. Statt einer Tabelle können Sie auch eine View oder eine Materialized View verwenden.

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC (
    updated_at timestamptz default sysdate not null,
    --at least one of external_id or alias_name and alias_label is required
    external_id varchar not null,.
    --if using user alias, both alias_name and alias_label are required
    alias_label varchar,
    alias_name varchar,
    properties varchar(max)
 );

Sie können Datenbank, Schema und Tabelle beliebig benennen, die Spaltennamen sollten jedoch der vorstehenden Definition entsprechen.

  • UPDATED_AT: Der Zeitpunkt, zu dem diese Zeile aktualisiert oder der Tabelle hinzugefügt wurde. Braze synchronisiert Zeilen, deren UPDATED_AT später als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenz-Zeitstempel können erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel haben.
  • Entweder external_id oder alias_name und alias_label als Spalte für den Nutzer-Bezeichner. Diese identifizieren die Nutzer:innen, für die Sie Canvas-Nachrichten triggern möchten.
    • EXTERNAL_ID: Identifiziert die Nutzer:in, die in das Canvas eintreten soll. Dieser Wert sollte mit dem in Braze verwendeten external_id-Wert übereinstimmen.
    • ALIAS_NAME und ALIAS_LABEL: Diese Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_label.
  • PROPERTIES: Ein JSON-String mit Feldern, die in Ihrem Canvas als Personalisierungseigenschaften verfügbar sein sollen. Er sollte nutzerspezifische Informationen enthalten.
Schritt 1.2: Zugangsdaten einrichten

Richten Sie eine Rolle, ein Warehouse und eine Nutzer:in ein und erteilen Sie die erforderlichen Berechtigungen. Wenn Sie bereits Zugangsdaten aus einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden. Stellen Sie jedoch sicher, dass der Zugriff auf die Quelltabelle für Canvas-Trigger erweitert wird.

CREATE USER braze_user PASSWORD '{password}';
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
GRANT SELECT ON TABLE CANVAS_TRIGGERS_SYNC TO braze_user;
Schritt 1.3: Netzwerkrichtlinien konfigurieren

Wenn Ihr Konto Netzwerkrichtlinien verwendet, setzen Sie die Braze-IPs auf die Allowlist, um die Verbindung zum CDI-Dienst zu ermöglichen. Die Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Schritt 1.1: Neues Projekt oder neuen Datensatz für Ihre Quelltabelle erstellen (optional)
CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;
Schritt 1.2: Quelltabelle in BigQuery einrichten

Orientieren Sie sich beim Erstellen Ihrer Quelltabelle an Folgendem:

Feldname Typ Erforderlich?
UPDATED_AT Timestamp Ja
PROPERTIES JSON Ja
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties JSON
);
Schritt 1.3: Zugangsdaten einrichten

Erstellen Sie eine Nutzer:in und erteilen Sie Berechtigungen. Wenn Sie bereits Zugangsdaten aus einer anderen Synchronisierung haben, können Sie diese wiederverwenden, sofern sie Zugriff auf die Tabelle für Canvas-Trigger haben.

Berechtigung Zweck
BigQuery Connection User Ermöglicht Braze, sich zu verbinden.
BigQuery User Ermöglicht Braze, Abfragen auszuführen, Metadaten zu lesen und Tabellen aufzulisten.
BigQuery Data Viewer Ermöglicht Braze, Datensätze und Inhalte anzuzeigen.
BigQuery Job User Ermöglicht Braze, Jobs auszuführen.

Legen Sie nach dem Erteilen der Berechtigungen fest, wie sich Braze als Dienstkonto authentifiziert:

Workload Identity Federation: Binden Sie den Braze-Principal an das Dienstkonto, sodass Sie keinen Schlüssel erstellen müssen. Die Schritte finden Sie unter Google Cloud für Workload Identity Federation konfigurieren.

Dienstkontoschlüssel: Generieren Sie einen JSON-Schlüssel. Eine Anleitung finden Sie unter Keys create and delete. Sie laden ihn später im Braze-Dashboard hoch.

Schritt 1.4: Netzwerkrichtlinien konfigurieren

Wenn Ihr Konto Netzwerkrichtlinien verwendet, setzen Sie die Braze-IPs auf die Allowlist, um die Verbindung zum CDI-Dienst zu ermöglichen. Die Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Schritt 1.1: Katalog oder Schema für Ihre Quelltabelle erstellen
CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Schritt 1.2: Quelltabelle in Databricks einrichten

Orientieren Sie sich beim Erstellen Ihrer Quelltabelle an Folgendem:

Feldname Typ Erforderlich
UPDATED_AT Timestamp Ja
PROPERTIES JSON Ja
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE

Sie können Schema und Tabelle beliebig benennen, die Spaltennamen sollten jedoch der vorstehenden Definition entsprechen.

  • UPDATED_AT: Der Zeitpunkt, zu dem diese Zeile aktualisiert oder der Tabelle hinzugefügt wurde. Braze synchronisiert Zeilen, deren UPDATED_AT später als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenz-Zeitstempel können erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel haben.
  • Entweder external_id oder alias_name und alias_label als Spalte für den Nutzer-Bezeichner. Diese identifizieren die Nutzer:innen, für die Sie Canvas-Nachrichten triggern möchten.
    • EXTERNAL_ID: Identifiziert die Nutzer:in, die in das Canvas eintreten soll. Dieser Wert sollte mit dem in Braze verwendeten external_id-Wert übereinstimmen.
    • ALIAS_NAME und ALIAS_LABEL: Diese Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_label.
  • PROPERTIES: Ein String oder Struct mit Feldern, die in Ihrem Canvas als Personalisierungseigenschaften verfügbar sein sollen. Er sollte nutzerspezifische Informationen enthalten.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp(),
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties STRING, STRUCT, or MAP
);
Schritt 1.3: Zugangsdaten einrichten

Erstellen Sie einen Service-Principal mit OAuth-Machine-to-Machine-Zugangsdaten (M2M, empfohlen) oder ein persönliches Zugriffstoken. Wenn Sie bereits Zugangsdaten aus einer anderen Synchronisierung haben, können Sie diese wiederverwenden, sofern sie Zugriff auf die Tabelle für Canvas-Trigger haben.

OAuth M2M: Erstellen Sie einen Service-Principal, generieren Sie ein Client-Secret, erteilen Sie dem Service-Principal die Berechtigung Can use für Ihr SQL-Warehouse und gewähren Sie ihm SELECT auf die Tabelle für Canvas-Trigger. Die Schritte finden Sie unter Zugangsdaten für Braze erstellen.

Persönliches Zugriffstoken:

  1. Wählen Sie Ihren Nutzernamen und dann User Settings aus.
  2. Wählen Sie im Tab Access tokens die Option Generate new token aus.
  3. Fügen Sie einen Kommentar hinzu, um das Token zu identifizieren, zum Beispiel „Braze CDI“.
  4. Lassen Sie Lifetime (days) leer, damit das Token nicht abläuft, und wählen Sie dann Generate aus.
  5. Kopieren Sie das Token und speichern Sie es sicher für die Verwendung im Braze-Dashboard.
Schritt 1.4: Netzwerkrichtlinien konfigurieren

Wenn Ihr Konto Netzwerkrichtlinien verwendet, setzen Sie die Braze-IPs auf die Allowlist, um die Verbindung zum CDI-Dienst zu ermöglichen. Die Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Schritt 1.1: Quelltabelle in Fabric einrichten
CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PROPERTIES VARCHAR NOT NULL,
  --at least one of external_id or alias_name and alias_label is required
  EXTERNAL_ID VARCHAR,
  --if using user alias, both alias_name and alias_label are required
  ALIAS_NAME VARCHAR,
  ALIAS_LABEL VARCHAR
)
GO
Schritt 1.2: Zugangsdaten einrichten

Erstellen Sie einen Service-Principal und erteilen Sie Berechtigungen. Wenn Sie bereits Zugangsdaten aus einer anderen Synchronisierung haben, können Sie diese wiederverwenden. Stellen Sie nur sicher, dass sie Zugriff auf die Kontentabelle haben.

Schritt 1.3: Netzwerkrichtlinien konfigurieren

Wenn Ihr Konto Netzwerkrichtlinien verwendet, setzen Sie die Braze-IPs auf die Allowlist, um die Verbindung zum CDI-Dienst zu ermöglichen. Die Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Um Canvas-Trigger aus einem Dateispeicher zu synchronisieren, erstellen Sie eine Quelldatei mit den folgenden Feldern.

Feld Erforderlich Beschreibung
EXTERNAL_ID Ja, entweder external_id oder alias_name und alias_label Identifiziert die Nutzer:in, die Sie aktualisieren möchten. Dieser Wert sollte mit dem in Braze verwendeten external_id-Wert übereinstimmen.
ALIAS_NAME und ALIAS_LABEL Ja, entweder external_id oder alias_name und alias_label Diese beiden Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_label.
PROPERTIES Ja JSON-String mit Feldern, die in Ihrem Canvas als Personalisierungseigenschaften verfügbar sein sollen. Er sollte nutzerspezifische Informationen enthalten.

Schritt 2: Ziel-Canvas konfigurieren

  1. Richten Sie Ihr Ziel-Canvas für Canvas-Trigger ein. Erstellen Sie ein neues API-getriggertes Canvas oder wählen Sie ein bestehendes aus. Unter Entry-Zeitplantypen erfahren Sie, wie Sie ein Canvas mit dem Zustellungszeitplantyp „API-getriggert“ erstellen.
  2. Nachdem Sie den Zustellungszeitplantyp „API-getriggert“ ausgewählt haben, fahren Sie mit der Canvas-Einrichtung fort und erstellen Sie Ihr Canvas. Canvases reichen von einfachen Einzelnachrichten bis hin zu komplexen Kund:innen-Workflows mit mehreren Schritten.
  3. Verwenden Sie in Ihren Canvas-Schritten Canvas-Entry-Eigenschaften, um Nachrichten mit den Eigenschaftsfeldern zu personalisieren, die Sie aus Ihrer Quelltabelle synchronisieren möchten.
    • Wenn Sie beispielsweise in Schritt 1 ein Eigenschaftsfeld für account_balance angelegt haben, verwenden Sie das folgende Liquid-Template, um Ihre Nachricht zu personalisieren: \{\{canvas_entry_properties.\$\{account_balance\}\}\}.
  4. Starten Sie Ihr Canvas, nachdem Sie es erstellt haben, und fahren Sie mit Schritt 3 fort.

Schritt 3: Zero-Copy-Synchronisierung erstellen

Wenn die Einrichtung der Quelle abgeschlossen und das Ziel-Canvas gestartet ist, erstellen Sie eine neue Datensynchronisierung:

  1. Gehen Sie in Braze zu Dateneinstellungen > Cloud-Datenaufnahme.
  2. Richten Sie die Verbindung ein, indem Sie die Verbindungsdetails eingeben (oder bestehende Zugangsdaten wiederverwenden) und die Quelltabelle aus Schritt 1 angeben.
  3. Geben Sie einen Namen für die Integration an.
  4. Wählen Sie den Datentyp Canvas-Trigger aus.
  5. Wählen Sie Ihr Ziel-Canvas (aus Schritt 2) aus.
  6. Wählen Sie eine Synchronisierungshäufigkeit aus.
  7. Legen Sie die Benachrichtigungseinstellungen fest.
  8. Wählen Sie Verbindung testen aus, um zu prüfen, ob alles wie erwartet funktioniert. Wenn Sie sich mit einem RSA-Schlüsselpaar mit Snowflake verbinden, fügen Sie zunächst den im Dashboard angezeigten Public Key der für Braze erstellten Nutzer:in hinzu. Für diesen Schritt benötigen Sie in Snowflake mindestens SECURITYADMIN-Zugriff. Wenn Sie sich mit Workload Identity Federation verbinden, führen Sie die Anweisung aus dem Formular für Zugangsdaten aus, bevor Sie die Verbindung testen. Siehe Snowflake für Workload Identity Federation konfigurieren.
  9. Speichern Sie die Synchronisierung, um mit der Synchronisierung der Canvas-Trigger zu beginnen.

  10. Wählen Sie Verbindung testen aus, um zu prüfen, ob alles wie erwartet funktioniert. Wenn Sie sich mit einem RSA-Schlüsselpaar mit Snowflake verbinden, fügen Sie zunächst den im Dashboard angezeigten Public Key der für Braze erstellten Nutzer:in hinzu. Für diesen Schritt benötigen Sie in Snowflake mindestens SECURITYADMIN-Zugriff. Wenn Sie sich mit Workload Identity Federation verbinden, führen Sie die Anweisung aus dem Formular für Zugangsdaten aus, bevor Sie die Verbindung testen. Siehe Snowflake für Workload Identity Federation konfigurieren.

Überlegungen

CDI-Canvas-Trigger nutzen Ihr REST-API-Rate-Limit für /canvas/trigger/send. Wenn Sie diesen Endpunkt gleichzeitig mit CDI-Canvas-Triggern und Ihrer REST-API-Integration verwenden, wird die gemeinsame Nutzung auf Ihr Rate-Limit angerechnet.

Jeder Synchronisierungslauf lässt Nutzer:innen mit einer maximalen Rate von etwa 3,75 Millionen Nutzer:innen pro Stunde in das jeweilige Ziel-Canvas eintreten. Rechnen Sie mit längeren Zeiten von der Quelle bis zum Canvas-Eintritt, wenn Sie:

  • mehr als 3,75 Millionen Nutzer:innen pro Synchronisierungslauf synchronisieren.
  • CDI-Canvas-Trigger verwenden, während Sie das Rate-Limit für /canvas/trigger/send Ihrer REST API bereits ausschöpfen.

Beachten Sie Folgendes zu Zero-Copy-CDI, wenn die Nachrichtenarchivierung aktiviert ist:

  • Die Ergebnisse der Tabelle werden während der Verarbeitung vorübergehend in Braze gespeichert. Sie werden außerdem für 30 Tage nach Snowflake exportiert, damit Sie genau sehen können, was synchronisiert wurde.
  • Archivierte Nachrichten werden nirgendwo in Braze gespeichert. Die Kopien werden ausschließlich an Ihren konfigurierten Speicher gesendet.
  • Bei der Verwendung von Zero-Copy-CDI mit Canvas-Triggern speichert Braze keine Sicherungskopie der Abfrageergebnisse aus dem Data Warehouse, und es werden keine Daten in das Nutzerprofil kopiert.
  • Canvas-Kontexteigenschaften können bis zu 30 Tage lang in internen Systemen protokolliert werden.
New Stuff!