Nachrichtenarchivierung
Mit der Nachrichtenarchivierung können Sie eine Kopie der an Nutzer:innen gesendeten Nachrichten zu Archivierungs- oder Compliance-Zwecken in Ihrem AWS S3-Bucket, Azure Blob Storage-Container oder Google Cloud Storage-Bucket speichern.
Dieser Artikel behandelt die Einrichtung der Nachrichtenarchivierung, JSON-Payload-Referenzen und häufig gestellte Fragen.
Die Nachrichtenarchivierung ist als zusätzliches Feature verfügbar. Um mit der Nachrichtenarchivierung zu beginnen, wenden Sie sich bitte an Ihren Braze-CSM.
Funktionsweise
Wenn dieses Feature aktiviert ist, schreibt Braze für jede Nachricht, die über Ihre ausgewählten Kanäle (E-Mail, SMS/MMS, Push oder In-App-Nachricht) an Nutzer:innen gesendet wird, eine gzip-komprimierte JSON-Datei. Braze schreibt diese Dateien in Ihr standardmäßiges Ziel für den Datenexport. Das umfasst alle Campaign-Typen für jeden Kanal, etwa Transaktions-E-Mail-Campaigns, die über die Transaktions-E-Mail-API gesendet werden.
Diese Datei enthält die unter Dateireferenzen definierten Felder und gibt die endgültigen, mit Templates erstellten Nachrichten wieder, die an die Nutzer:innen gesendet wurden. Alle in Ihrer Campaign definierten Template-Werte (zum Beispiel {{${first_name}}}) zeigen den endgültigen Wert, den die Nutzer:innen auf Grundlage ihrer Profilinformationen erhalten haben. So können Sie eine Kopie der gesendeten Nachricht aufbewahren, um Compliance-, Audit- oder Kundensupport-Anforderungen zu erfüllen.
Wenn Sie Zugangsdaten für mehrere Cloud-Speicheranbieter eingerichtet haben, exportiert die Nachrichtenarchivierung nur zu dem Anbieter, der als Standardziel für den Datenexport markiert ist. Wenn Sie kein explizites Standardziel festlegen und ein AWS S3-Bucket verbunden ist, lädt die Nachrichtenarchivierung die Dateien in diesen Bucket hoch.
Die Aktivierung dieses Features wirkt sich auf die Zustellungsgeschwindigkeit Ihrer Nachrichten aus, da der Datei-Upload aus Gründen der Genauigkeit unmittelbar vor dem Versand der Nachricht erfolgt. Die durch die Nachrichtenarchivierung verursachte Latenz hängt vom Cloud-Speicheranbieter sowie vom Durchsatz und der Größe der gespeicherten Dokumente ab.
Die JSON-Datei wird in Ihrem Speicher-Bucket mit der folgenden Schlüsselstruktur gespeichert:
sent_messages/{channel, one of: email, push, sms}/{MD5 digest of downcased: email address, push token, or E.164 phone number}/{campaign or Canvas step API ID}/{dispatch ID}.json.gz
Eine Beispieldatei könnte so aussehen:
sent_messages/email/819baa08d8d7e77e19d4666f5fc6050b/ee965cb2-8934-4b0a-acf1-91c899c2f915/651fd10b282850b39e1169c13975234b.json.gz
Der MD5-Digest kann nur anhand einer bekannten, in Kleinbuchstaben umgewandelten E-Mail-Adresse, eines Push-Tokens oder einer E.164-Telefonnummer berechnet werden. Aus einem bekannten MD5-Digest lässt sich die in Kleinbuchstaben umgewandelte E-Mail-Adresse, der Push-Token oder die E.164-Telefonnummer nicht zurückgewinnen.
Sie finden Ihre Push-Token nicht in Ihren Buckets?
Braze wandelt Ihre Push-Token in Kleinbuchstaben um, bevor sie gehasht werden. Dadurch wird beispielsweise der Push-Token Test_Push_Token12345 im Schlüsselpfad zu test_push_token12345 mit dem Hash 32b802170652af2b5624b695f34de089.
Einrichten der Nachrichtenarchivierung
In diesem Abschnitt erfahren Sie, wie Sie die Nachrichtenarchivierung für Ihren Workspace einrichten. Vergewissern Sie sich zunächst, dass Ihr Unternehmen die Nachrichtenarchivierung erworben und aktiviert hat.
Schritt 1: Cloud-Storage-Bucket verbinden
Falls noch nicht geschehen, verbinden Sie einen Cloud-Storage-Bucket mit Braze. Die einzelnen Schritte finden Sie in unserer Partner-Dokumentation zu Amazon S3, Azure Blob Storage oder Google Cloud Storage.
Für die Nachrichtenarchivierung müssen Sie Currents nicht einrichten. Diese Voraussetzung in der Partner-Dokumentation können Sie also überspringen.
Schritt 2: Kanäle für die Nachrichtenarchivierung auswählen
Auf der Einstellungsseite Nachrichtenarchivierung legen Sie fest, welche Kanäle eine Kopie der gesendeten Nachrichten in Ihrem Cloud-Storage-Bucket speichern.
So wählen Sie die Kanäle aus:
- Gehen Sie zu Einstellungen > Nachrichtenarchivierung.
- Wählen Sie Ihre Kanäle aus.
- Wählen Sie Änderungen speichern.
Wenn Sie Nachrichtenarchivierung unter Einstellungen nicht sehen, vergewissern Sie sich, dass Ihr Unternehmen die Nachrichtenarchivierung erworben und aktiviert hat.
Wenn Sie die Nachrichtenarchivierung für In-App-Nachrichten aktivieren, werden alle Ihre In-App-Nachrichten in In-App-Nachrichten mit Template umgewandelt. Das bedeutet, dass eine Netzwerkanfrage erforderlich ist, bevor Braze die Nachricht anzeigen kann. Weitere Informationen finden Sie unter Was passiert, wenn ich die Nachrichtenarchivierung für In-App-Nachrichten aktiviere?.
IP-Allowlisting
Wenn die Nachrichtenarchivierung Dateien in Ihren Cloud-Storage-Bucket hochlädt, sendet Braze Netzwerkanfragen von unseren Servern an Ihren Endpunkt bei AWS S3, Azure Blob Storage oder Google Cloud Storage. Mit IP-Allowlisting können Sie überprüfen, ob diese Anfragen von Braze stammen. So erhalten Sie eine zusätzliche Sicherheitsebene.
Braze sendet die Uploads der Nachrichtenarchivierung von denselben IP-Adressen, die auch für Connected-Content und Currents verwendet werden. Die vollständige Liste der IPs nach Instanz finden Sie unter IP-Allowlisting für Connected-Content.
Datei-Referenzen
Im Folgenden finden Sie Referenzen zum JSON-Payload, der bei jedem Versand einer Nachricht an Ihren Cloud-Storage-Bucket übermittelt wird. Beispieldateien finden Sie in unserem Code-Beispiel-Repository unter Beispieldateien für die Nachrichtenarchivierung.
{
"version": 1, //numerical version of the JSON structure
"to": ToAddress, ("[email protected]")
"subject": SubjectLine ("20% off coupon inside!"),
"from_name": DisplayName ("Braze"),
"from_address": FromAddress ("[email protected]"),
"html_body": HtmlBody,
"plaintext_body": PlainTextBody,
"amp_body": AMPEmailBody,
"extras": Hash of key-value pairs from Email Extras configured in the email editor,
"headers": HashOfHeaders,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessageVariationApiId, // may not be available,
"attachments": Array of JSON Objects containing 'bytes' and 'file_name', // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Das Feld extras enthält die Schlüssel-Wert-Paare, die beim Verfassen einer E-Mail im HTML-Editor im Feld E-Mail-Extras konfiguriert wurden. E-Mail-Extras funktionieren mit allen E-Mail-Anbietern (einschließlich SendGrid und Sparkpost) und sind in archivierten Nachrichten enthalten, unabhängig davon, welcher Anbieter verwendet wird. Weitere Informationen zur Konfiguration von E-Mail-Extras finden Sie unter E-Mail-Campaign erstellen. Informationen zum Zurücksenden von Daten an Currents finden Sie unter Nachrichten-Extras.
{
"version": 1 //numerical version of the JSON structure
"to": PhoneNumber, ("+15555555555"),
"body": Body ("Hi there!"),
"subscription_group": SubscriptionGroupExternalId,
"provider": StringOfProviderName,
"media_urls": ArrayOfString, // indicates a message is MMS
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessagVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
{
"version": 1, //numerical version of the JSON structure
"to": PushToken,
"payload": JsonOfEntirePushPayload,
"platform": one of "android_push" | "ios_push" | "kindle_push" | "web_push",
"app_id": ApiKeyOfApp,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessagVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Variationen der Push-Payload-Struktur
Das übergeordnete Feld payload in Archiven von Push-Benachrichtigungen enthält den gesamten Anbieter-Payload, wie er an das Gerät gesendet wurde. Innerhalb dieses JSON können Schlüssel wie aps (für APNs) oder notification und data (für FCM) je nach Nachrichtentyp, Plattform und Konfiguration erheblich variieren.
Die Nachrichtenarchivierung erfasst den Nachrichten-Payload selbst, enthält jedoch keine Zustellungsmetadaten, die an FCM oder APNs gesendet werden. Zu den Zustellungsmetadaten gehören:
- Geräte-Token
- Prioritätseinstellungen
- Time-to-live (TTL)
- Collapse-IDs
- APNs-Header
- Ablaufzeitstempel
- Weitere Felder zur Zustellungskonfiguration
Diese Felder dienen als Zustellungsanweisungen für den Push-Anbieter. Sie gelten in der Regel nicht als Teil des Nachrichteninhalts.
Zum Beispiel:
- iOS-Push-Benachrichtigungen können bei Rich-Benachrichtigungen (bei denen
aps.alertein Objekt mit Feldern wietitleundbodyist) eine andere Struktur haben als bei einfachen Benachrichtigungen (bei denenaps.alertein String ist). - Android-Push-Benachrichtigungen (zum Beispiel FCM) verwenden Datennachrichten mit angepassten Schlüsseln. Die Payload-Struktur kann je nach Nachrichtenkonfiguration unterschiedliche optionale Felder enthalten, etwa Push-Buttons, Karussells oder zusätzliche Metadaten.
Außerdem können Testsendungen aus dem Dashboard andere Payload-Strukturen erzeugen als Produktionsnachrichten.
Das Format des JSON-Payloads kann von Nachricht zu Nachricht variieren und sich im Laufe der Zeit ändern. Gehen Sie beim Parsen archivierter Push-Payloads nicht von einer festen Struktur aus und erwarten Sie nicht, dass immer dieselben Felder vorhanden sind. Implementieren Sie eine flexible Parsing-Logik, die verschiedene Payload-Formate verarbeiten kann.
{
"version": 1, //numerical version of the JSON structure
"to": UserId, // the message recipient's identifier, typically matches user_id
"payload": JsonOfEntireInAppMessagePayload,
"platform": StringOfPlatformName, ("web")
"device_identifier": DeviceIdentifier, // may not be available
"app_id": ApiKeyOfApp,
"sent_at": UnixTimestamp,
"dispatch_id": DispatchIdFromBraze,
"campaign_id": CampaignApiId, // may not be available
"canvas_id": CanvasApiId, // may not be available
"canvas_step_id": CanvasStepApiId, // may not be available
"canvas_variation_id" : CanvasVariationApiId, // may not be available
"message_variation_id": MessageVariationApiId, // may not be available
"user_id": String,
"campaign_name": String, // will only be available if the message is from a campaign
"canvas_name": String, // will only be available if the message is from a Canvas
"canvas_step_name": String, // will only be available if the message is from a Canvas
"external_id": String
}
Variationen der Payload-Struktur von In-App-Nachrichten
Das übergeordnete Feld payload in Archiven von In-App-Nachrichten enthält die vollständige Konfiguration der In-App-Nachricht, einschließlich ihres Inhalts (etwa Nachrichtentext und Header) und der Anzeigeeinstellungen (etwa Nachrichtentyp, Textausrichtung und Farben). Welche Felder genau vorhanden sind, hängt vom Typ der In-App-Nachricht ab, zum Beispiel Modal, Slideup, Vollbild oder Angepasstes HTML.
Das Format des JSON-Payloads kann von Nachricht zu Nachricht variieren und sich im Laufe der Zeit ändern. Gehen Sie beim Parsen archivierter Payloads von In-App-Nachrichten nicht von einer festen Struktur aus und erwarten Sie nicht, dass immer dieselben Felder vorhanden sind. Implementieren Sie eine flexible Parsing-Logik, die verschiedene Payload-Formate verarbeiten kann.
Häufig gestellte Fragen
Was passiert, wenn ich die Nachrichtenarchivierung für In-App-Nachrichten aktiviere?
Wenn Sie die Nachrichtenarchivierung für In-App-Nachrichten aktivieren, werden alle In-App-Nachrichten zu In-App-Nachrichten mit Template. Das bedeutet, dass eine Netzwerkanfrage erforderlich ist, bevor Braze die Nachricht anzeigen kann.
Welches Templating ist nicht im Payload enthalten?
Änderungen, die vorgenommen werden, nachdem die Nachricht Braze verlassen hat, werden nicht in der Datei berücksichtigt, die in Ihrem Cloud-Storage-Bucket gespeichert wird. Dazu gehören Änderungen durch unsere Partner für die E-Mail-Zustellung, etwa das Umschließen von Links für das Klick-Tracking und das Einfügen von Tracking-Pixeln.
Was sind Nachrichten unter dem Wert „unassociated“ im Campaign-Pfad?
Wenn eine Nachricht außerhalb einer Campaign oder eines Canvas versendet wird, lautet die Campaign-ID im Dateinamen „unassociated“. Das ist der Fall, wenn Sie Testnachrichten aus dem Dashboard senden, wenn Braze automatische SMS/MMS-Antworten sendet oder wenn über die API gesendete Nachrichten keine Campaign-ID angeben.
Wie finde ich weitere Informationen zu diesem Versand?
Sie können entweder die external_id oder die dispatch_id zusammen mit der user_id verwenden, um die Nachricht mit Template mit unseren Currents-Daten abzugleichen. So finden Sie weitere Informationen, etwa den Zeitstempel der Zustellung, ob Nutzer:innen die Nachricht geöffnet oder angeklickt haben, und mehr.
Wie werden Wiederholungsversuche gehandhabt?
Wenn Ihr Cloud-Storage-Bucket nicht erreichbar ist, versucht Braze es bis zu dreimal erneut mit einem Backoff-Jitter. Wiederholungsversuche aufgrund von AWS S3-Rate-Limits werden automatisch von Braze gehandhabt.
Was passiert, wenn meine Zugangsdaten ungültig sind?
Wenn Ihre Zugangsdaten für den Cloud-Speicher zu irgendeinem Zeitpunkt ungültig werden, kann Braze keine Nachrichten in Ihrem Cloud-Storage-Bucket speichern, und diese Nachrichten gehen verloren. Wir empfehlen, Ihre Benachrichtigungseinstellungen für Amazon Web Services, Google Cloud Services oder Azure (Microsoft Cloud Services) zu konfigurieren, damit Sie bei Problemen mit den Zugangsdaten benachrichtigt werden.
Warum weicht der sent_at-Zeitstempel meiner Archivdatei leicht vom Versand-Zeitstempel in Currents ab?
Die gerenderte Kopie wird unmittelbar vor dem Versand der Nachricht an die Nutzer:innen hochgeladen. Aufgrund der Upload-Zeiten des Cloud-Speichers kann es zwischen dem sent_at-Zeitstempel in der gerenderten Kopie und dem tatsächlichen Versandzeitpunkt eine Verzögerung von einigen Sekunden geben.
Kann ich einen neuen Bucket speziell für die Nachrichtenarchivierung erstellen und gleichzeitig den aktuellen Bucket für Currents-Daten beibehalten?
Nein. Wenn Sie an dedicated message archiving buckets while keeping a separate Currents bucket interessiert sind, reichen Sie Produktfeedback ein.
Werden archivierte Daten in einen eigenen Ordner in einem bestehenden Bucket geschrieben, ähnlich wie Currents-Datenexporte strukturiert sind?
Die Daten werden in einen Bereich sent_messages des Buckets geschrieben. Weitere Details finden Sie unter Funktionsweise.
Kann ich mit der Nachrichtenarchivierung Dateien nach Workspaces gruppieren?
Nein. Die Nachrichtenarchivierung unterstützt keine Gruppierung von Dateien nach Workspaces. Stattdessen können Sie ermitteln, zu welchem Workspace die API-ID der Campaign oder des Canvas-Schritts gehört, und die Dateien anhand dieser Information gruppieren.