Schlüssel-Wert-Paare
Diese Seite beschreibt, wie Sie Schlüssel-Wert-Paare verwenden können, um zusätzliche Daten-Payloads an Nutzergeräte zu senden. Dieses Feature ist über Push-, In-App-, E-Mail- und Content-Card-Messaging-Kanäle verfügbar.
Verwenden Sie Schlüssel-Wert-Paare, um strukturierte Metadaten zu Nachrichten hinzuzufügen. Diese zusätzlichen Daten-Payloads können Nachrichten mit weiteren kontextuellen Informationen anreichern, die beeinflussen können, wie eine Nachricht dargestellt oder verarbeitet wird.
Da Schlüssel-Wert-Paare Metadaten sind, sind diese Daten nicht unbedingt für die Empfänger:innen sichtbar, können aber von Ihren verbundenen Systemen oder Prozessen verwendet werden, um die Nachrichtenverarbeitung anzupassen.
Jedes Paar besteht aus:
- Schlüssel: Der Bezeichner (Beispiel:
utm_source) - Wert: Die zugehörigen Daten (Beispiel:
newsletter)
Anwendungsfälle
Hier sind einige Beispiele für Anwendungsfälle, in denen Sie Metadaten mit Schlüssel-Wert-Paaren hinzufügen können:
- Tracking-Parameter: UTM-Parameter für Analytics-Zwecke anhängen
- Schlüssel:
utm_campaign - Wert:
spring_sale
- Schlüssel:
- Angepasste Tags: Tags für internes Routing oder zur Kategorisierung hinzufügen
- Schlüssel:
priority - Wert:
high
- Schlüssel:
- Verhaltens-Trigger: Metadaten, die zum Triggern oder Anpassen von In-App-Verhalten verwendet werden
- Schlüssel:
deep_link - Wert:
app://promo-page
- Schlüssel:
Push-Benachrichtigungen
Schlüssel-Wert-Paare können zu Android-, iOS- und Web-Push-Benachrichtigungen hinzugefügt werden. Mit Schlüssel-Wert-Paaren können Sie interne Metriken und App-Inhalte aktualisieren oder Eigenschaften von Push-Benachrichtigungen anpassen, etwa die Priorisierung von Alerts, die Lokalisierung und Sounds.
Wählen Sie im Nachrichten-Editor den Tab Einstellungen aus, wählen Sie Neues Paar hinzufügen und geben Sie Ihre Schlüssel-Wert-Paare an.
Wenn Sie im Nachrichten-Editor Schlüssel-Wert-Paare hinzufügen, werden die Werte als Strings gesendet. Bei iOS-Push werden reservierte Alert-Schlüssel des Apple Push Notification Service (APNs), die Sie über Alert-Optionen hinzufügen (etwa loc-args für Lokalisierungsargumente), im Payload mit den korrekten JSON-Typen formatiert. Bei angepassten Schlüsseln empfängt Ihre App String-Werte, sofern Sie diese nicht in Ihrer Integration parsen.
iOS
Der Apple Push Notification Service (APNs) unterstützt das Festlegen von Alert-Einstellungen und das Senden angepasster Daten über Schlüssel-Wert-Paare. APNs nutzt die von Apple reservierte Bibliothek aps, die vordefinierte Schlüssel und Werte enthält, mit denen die Alert-Eigenschaften gesteuert werden.
APS-Bibliothek
| Schlüssel | Werttyp | Wertbeschreibung |
|---|---|---|
| alert | String oder Wörterbuch-Objekt | Bei String-Eingaben wird ein Alert mit dem String als Nachricht sowie den Buttons „Schließen“ und „Anzeigen“ angezeigt; bei anderen Eingaben wird je nach den untergeordneten Eigenschaften der Eingabe ein Alert oder ein Banner angezeigt |
| badge | Zahl | Steuert die Zahl, die als Badge auf dem App-Symbol angezeigt wird |
| sound | String | Der Name der Sounddatei, die als Alert abgespielt werden soll; muss sich im Bundle der App oder im Ordner Library/Sounds befinden |
| content-available | Zahl | Der Eingabewert 1 signalisiert der App, dass beim Start oder bei der Wiederaufnahme der Sitzung neue Informationen verfügbar sind |
Bibliothek für Alert-Eigenschaften
| Schlüssel | Werttyp | Wertbeschreibung |
|---|---|---|
| title | String | Ein kurzer String, den die Apple Watch kurz als Teil einer Benachrichtigung anzeigt |
| body | String | Der Inhalt der Push-Benachrichtigung |
| title-loc-key | String oder null | Ein Schlüssel, der den Titel-String für die aktuelle Lokalisierung aus der Datei Localizable.strings festlegt |
| title-loc-args | String-Array oder null | String-Werte, die anstelle der Formatbezeichner für die Titel-Lokalisierung in title-loc-key erscheinen können |
| action-loc-key | String-Array oder null | Falls vorhanden, legt der angegebene String die Lokalisierung für die Buttons „Schließen“ und „Anzeigen“ fest |
| loc-key | String oder null | Ein Schlüssel, der die Benachrichtigungsnachricht für die aktuelle Lokalisierung aus der Datei Localizable.strings festlegt |
| loc-args | String-Array | String-Werte, die anstelle der Formatbezeichner für die Lokalisierung in loc-key erscheinen können |
| launch-image | Strings | Der Name einer Bilddatei im App-Bundle, die als Startbild verwendet werden soll, wenn Nutzer:innen auf den Aktions-Button tippen oder den Aktionsschieberegler bewegen |
Der Braze Nachrichten-Editor übernimmt automatisch die Erstellung der folgenden Schlüssel: alert und seine Eigenschaften, content-available, sound und category.
Diese Werte können Sie beim Erstellen einer Push-Nachricht im Tab Einstellungen eingeben. Wählen Sie Alert-Optionen und dann einen Schlüssel aus dem Alert-Wörterbuch aus, damit der Schlüssel automatisch in einem neuen Schlüssel-Wert-Eintrag ausgefüllt wird.
Wenn Braze eine Push-Benachrichtigung an APNs sendet, wird der Payload als JSON formatiert.
Einfacher Payload
{
"aps" : { "alert" : "Message received from Spencer" },
}
Komplexer Payload
{
"aps" : {
"alert" : {
"body" : "Hi, welcome to our app!",
"loc-key" : "France",
"loc-args" : ["Bonjour", "bienvenue"],
"action-loc-key" : "Button_Type_1",
"launch-image" : "Paris"
},
"content-available" : 1
},
}
Angepasste Schlüssel-Wert-Paare
Zusätzlich zu den Payload-Werten der Bibliothek aps können Sie angepasste Schlüssel-Wert-Paare an das Gerät von Nutzer:innen senden. Die Werte in diesen Paaren sind auf primitive Typen beschränkt: Wörterbuch (Objekt), Array, String, Zahl und Boolean.
Anwendungsfälle für angepasste Schlüssel-Wert-Paare sind unter anderem das Führen interner Metriken und das Festlegen des Kontexts für die Benutzeroberfläche. Mit Braze können Sie zusammen mit einer Push-Benachrichtigung zusätzliche Schlüssel-Wert-Paare senden, die Ihre Anwendung über den extras-Schlüssel nutzen kann. Wenn Sie lieber einen anderen Schlüssel verwenden möchten, stellen Sie sicher, dass Ihre App diesen angepassten Schlüssel verarbeiten kann.
Vermeiden Sie es, in Ihrer Anwendung einen Top-Level-Schlüssel oder ein Wörterbuch namens ab zu verarbeiten.
Apple rät Clients davon ab, Kundeninformationen oder andere sensible Daten als angepasste Payload-Daten einzufügen. Darüber hinaus empfiehlt Apple, dass keine mit einer Alert-Nachricht verbundene Aktion Daten auf einem Gerät löschen sollte.
Wenn Sie die HTTP/2-Provider-API verwenden, darf ein einzelner Payload, den Sie an APNs senden, nicht größer als 4096 Bytes sein. Die alte binäre Schnittstelle, die bald eingestellt wird, unterstützt nur eine Payload-Größe von 2048 Bytes.
API-getriggerte Campaigns
Mit Braze können Sie angepasste String-Schlüssel-Wert-Paare senden, die als extras bezeichnet werden. Um in API-getriggerten und geplanten API-getriggerten Campaigns auf Ihre Extras zuzugreifen, legen Sie im Dashboard einen Schlüssel als „example_key“ und einen Wert als "$json:{"foo": 1, "bar": 1}" fest. Daraus ergibt sich in der Entwicklungskonsole die Ausgabe "extras": { "test": { "foo": 1, "bar": 1 }
Android
Mit Braze können Sie über Schlüssel-Wert-Paare zusätzliche Daten-Payloads in Push-Benachrichtigungen senden.
Daten-Payload
Ähnlich wie bei iOS-Push können Sie angepasste Schlüssel-Wert-Paare an das Gerät von Nutzer:innen senden.
Zu den Anwendungsfällen für angepasste Schlüssel-Wert-Paare gehören das Führen interner Metriken und das Festlegen des Kontexts für die Benutzeroberfläche. Sie können sie aber für jeden beliebigen Zweck verwenden.
Das Backend Ihrer App muss angepasste Schlüssel-Wert-Paare verarbeiten können, damit der Daten-Payload korrekt funktioniert.
API-getriggerte Campaigns
Mit Braze können Sie angepasste String-Schlüssel-Wert-Paare senden, die als extras bezeichnet werden. Um in API-getriggerten und geplanten API-getriggerten Campaigns auf Ihre Extras zuzugreifen, legen Sie im Dashboard einen Schlüssel als „example_key“ und einen Wert als "$json:{"foo": 1, "bar": 1}" fest. Daraus ergibt sich in der Entwicklungskonsole die Ausgabe "extras": { "test": { "foo": 1, "bar": 1 }.
FCM-Messaging-Optionen
Android-Push-Benachrichtigungen lassen sich mit FCM-Nachrichtenoptionen weiter anpassen. Dazu gehören Benachrichtigungspriorität, Sound, Verzögerung, Lebensdauer und Zusammenfassbarkeit. Diese Werte können Sie beim Erstellen einer Push-Nachricht im Tab Einstellungen festlegen. Weitere Anweisungen zum Festlegen dieser Optionen im Braze Nachrichten-Editor finden Sie unter Erweiterte Einstellungen für Push-Benachrichtigungen.
Stille Push-Benachrichtigungen
Eine stille Push-Benachrichtigung ist eine Push-Benachrichtigung ohne Alert-Nachricht oder Sound, mit der die Oberfläche oder der Inhalt Ihrer App im Hintergrund aktualisiert wird. Diese Benachrichtigungen nutzen Schlüssel-Wert-Paare, um diese Hintergrundaktionen der App zu triggern. Stille Push-Benachrichtigungen bilden außerdem die Grundlage für unser Uninstall-Tracking.
Marketer sollten testen, ob stille Push-Benachrichtigungen das erwartete Verhalten triggern, bevor sie diese an die Nutzer:innen ihrer App senden. Nachdem Sie Ihre stille Push-Benachrichtigung für iOS oder Android erstellt haben, stellen Sie sicher, dass Sie nur eine:n Testnutzer:in ansprechen, indem Sie nach externer Nutzer-ID oder E-Mail-Adresse filtern.
Überprüfen Sie nach dem Start der Campaign, dass Sie auf Ihrem Testgerät keine sichtbare Push-Benachrichtigung erhalten haben.
Die Einschränkung stiller Benachrichtigungen durch iOS kann folgende Symptome verursachen:
- Niedrigere Metriken für das Uninstall-Tracking bei iOS-Nutzer:innen als erwartet
- Inkonsistente oder verzögerte Zustellung stiller Push-Benachrichtigungen
- Push Stories, die nicht angezeigt werden
- Push Stories, die ohne die erwarteten Bilder, Videos oder Seiten ankommen
Dies ist eine Einschränkung der Apple-Plattform und kein Problem von Braze. iOS kann Hintergrundbenachrichtigungen für einige Braze-Features verzögern oder verwerfen, darunter Uninstall-Tracking und Push Stories. Einzelheiten dazu, was iOS einschränkt und wann, finden Sie unter iOS-Einschränkungen.
In-App-Nachrichten
Sie können jeder In-App-Nachricht, die Sie im Editor erstellen, Schlüssel-Wert-Paare hinzufügen.
- Erstellen oder bearbeiten Sie in Ihrer Campaign oder Ihrem Canvas eine In-App-Nachricht.
- Wählen Sie im Nachrichten-Editor den Tab Einstellungen aus.
- Wählen Sie unter Schlüssel-Wert-Paare die Option Neues Paar hinzufügen aus.
- Geben Sie für jedes Paar einen Schlüssel und einen Wert ein. Um ein weiteres Paar hinzuzufügen, wählen Sie erneut Neues Paar hinzufügen aus.
API-getriggerte Campaigns
Mit Braze können Sie angepasste String-Schlüssel-Wert-Paare senden, die als extras bezeichnet werden. Um in API-getriggerten und geplanten API-getriggerten Campaigns auf Ihre Extras zuzugreifen, legen Sie im Dashboard einen Schlüssel als „example_key“ und einen Wert als "$json:{"foo": 1, "bar": 1}" fest. Daraus ergibt sich in der Entwicklungskonsole die Ausgabe "extras": { "test": { "foo": 1, "bar": 1 }.
E-Mails
Sowohl SparkPost als auch SendGrid unterstützen Schlüssel-Wert-Paare in E-Mails. Wenn Sie SendGrid verwenden, werden Schlüssel-Wert-Paare als eindeutige Argumente gesendet. SendGrid erlaubt es Ihnen, eine unbegrenzte Anzahl von Schlüssel-Wert-Paaren mit bis zu 10.000 Byte an Daten anzuhängen. Diese Schlüssel-Wert-Paare sind in Posts des SendGrid Event Webhook sichtbar.
Bei E-Mails mit Bounce werden keine Schlüssel-Wert-Paare an SparkPost oder SendGrid übermittelt.
Content Cards
Um ein Schlüssel-Wert-Paar zu einer Content Card hinzuzufügen, gehen Sie zum Tab Settings im Braze-Nachrichten-Editor und wählen Sie Add New Pair.
Kontrollvarianten unterstützen keine Schlüssel-Wert-Paare. Wenn Sie Analytics für Kontrollgruppen in A/B-Tests erfassen müssen, erstellen Sie eine Nachrichtenvariante mit einem Schlüssel-Wert-Paar wie control=true und blenden Sie diese in Ihrem App-Code aus, während Sie Impressionen protokollieren.