PassKit

PassKit ermöglicht es Ihnen, Ihre mobile Reichweite zu erweitern, indem Sie Apple Wallet und Google Pay Pässe in das Kundenerlebnis integrieren. Erstellen, verwalten, verteilen und analysieren Sie ganz einfach die Performance von digitalen Coupons, Kundenkarten, Mitgliedskarten, Tickets und vielem mehr – ohne dass Ihre Kund:innen eine weitere App benötigen.

Diese Integration wird von PassKit gepflegt.

Über die Integration

Mit der Integration von Braze und PassKit können Sie das Engagement Ihrer Online-Kampagnen steigern und messen, indem Sie sofort angepasste Pässe für Apple Wallet und Google Pay bereitstellen. Anschließend können Sie die Nutzung analysieren und in Realtime Anpassungen vornehmen, um mehr Besucher:innen in Ihre Geschäfte zu bringen. Dazu triggern Sie standortbasierte Nachrichten sowie personalisierte, dynamische Updates für das Mobile Wallet Ihrer Kund:innen.

Voraussetzungen

Integration

Um die Erfahrungen Ihrer Kund:innen mit der mobilen Wallet weiter zu verbessern, können Sie von Ihrem PassKit-Dashboard aus Daten über den Braze /users/track-Endpunkt an Braze weitergeben.

Beispiele für Daten, die Sie von PassKit weitergeben können:

• Pass erstellt: wenn ein:e Kund:in auf einen Pass-Link klickt und zum ersten Mal einen Pass angezeigt bekommt.
• Pass-Installationen: wenn der/die Kund:in den Pass in seine/ihre Wallet-App einfügt und speichert.
• Pass-Updates: wenn ein Pass aktualisiert wird.
• Pass löschen: wenn ein:e Kund:in den Pass aus seiner/ihrer Wallet-App löscht.

Sobald die Daten an Braze übergeben wurden, können Sie Zielgruppen aufbauen, Inhalte über Liquid personalisieren und Campaigns oder Canvases triggern, nachdem diese Aktionen durchgeführt wurden.

Passkit mit Braze verbinden

Um Daten von PassKit zu übermitteln, stellen Sie sicher, dass Sie Ihre externe Braze-ID als externalId von PassKit festgelegt haben.

1. Klicken Sie in Ihrem PassKit-Pass-Projekt oder -Programm unter Einstellungen im Bereich Integrationen auf dem Tab Braze auf Verbinden.
   
   
   
2. Geben Sie Ihren Braze-API-Schlüssel und die Endpunkt-URL ein und legen Sie einen Namen für Ihren Konnektor fest.
   
   
3. Aktivieren Sie Integration aktivieren sowie alle Events, mit denen Sie in Braze Ihre Nachrichten triggern oder personalisieren möchten.
   

Pass mit einem SmartPass-Link erstellen

In Braze können Sie einen SmartPass-Link einrichten, der eine eindeutige URL generiert, über die Ihre Kund:innen ihren Pass auf Android oder iOS installieren können. Dazu definieren Sie eine verschlüsselte SmartPass-Daten-Payload, die aus einem Braze Content-Block aufgerufen werden kann. Diesen Content-Block können Sie anschließend für zukünftige Pässe und Coupons wiederverwenden. Für Ihre Integration benötigen Sie Folgendes:

• PassKit-URL: Ihre PassKit-URL ist eine eindeutige URL für Ihr PassKit-Programm.
  Jedes Programm hat eine eindeutige URL. Sie finden sie im Tab Distribution Ihres PassKit-Programms oder -Projekts (zum Beispiel https://pub1.pskt.io/c/ww0jir).
  
  
• PassKit-Secret: Zusätzlich zur URL benötigen Sie den PassKit-Schlüssel für dieses Programm.
  Sie finden ihn auf derselben Seite wie Ihre PassKit-URL.
  
  
• Programm- (oder Projekt-) ID: Ihre PassKit-Programm-ID ist erforderlich, um die SmartPass-URL zu erstellen.
  Sie finden sie im Tab Settings Ihres Projekts oder Programms.

Weitere Informationen zum Erstellen verschlüsselter SmartPass-Links finden Sie unter PassKit SmartPass-Links auf der Website von PassKit.

Schritt 1: Payload Ihrer Pass-Daten definieren

Zunächst müssen Sie die Coupon- oder Mitglieder-Payload definieren.

Sie können viele verschiedene Komponenten in Ihre Payload aufnehmen, zwei davon sind jedoch besonders wichtig:

Eine vollständige Liste der verfügbaren Felder, ihrer Typen und hilfreicher Beschreibungen finden Sie in der GitHub-Dokumentation von PassKit.

Beispiel-Payload

1
2
3
4
5
6
7
8

{
  "members.member.externalId": "{{${user_id}}}",
  "members.member.points": "100",
  "members.tier.name": "current_customer",
  "person.displayName": "{{${first_name}}} {{${last_name}}}",
  "person.externalId": "{{${user_id}}}",
  "universal.expiryDate": "{{ "now" | date: "%s" | plus: 31622400 | date: "%FT%TZ" }}"
}

Schritt 2: Undefinierte Payload-Variable erstellen und kodieren

Erstellen und benennen Sie einen neuen Content-Block, indem Sie im Braze-Dashboard zu Inhalt > Content-Block navigieren.

Wählen Sie Content-Block erstellen, um zu beginnen.

Als Nächstes müssen Sie Ihren Content-Block Liquid-Tag definieren. Nachdem Sie diesen Content-Block gespeichert haben, können Sie beim Verfassen von Nachrichten auf diesen Liquid-Tag verweisen. In diesem Beispiel haben wir den Liquid-Tag {{content_blocks.${passKit_SmartPass_url}}} zugewiesen.

In diesen Content-Block fügen wir die Payload nicht direkt ein, sondern verweisen über eine Variable {{passData}} darauf. Das erste Code-Snippet, das Sie Ihrem Content-Block hinzufügen müssen, erfasst eine Base64-Kodierung der Variable {{passData}}.

1

{% capture base64JsonPayload %}{{passDatapassData|base64_encode}}{% endcapture %}

Schritt 3: Verschlüsselungssignatur mit einem SHA1-HMAC-Hash erstellen

Als Nächstes erstellen Sie Ihre Verschlüsselungssignatur mithilfe eines SHA1-HMAC-Hashs aus der Projekt-URL und der Payload.

Das zweite Code-Snippet, das Sie Ihrem Content-Block hinzufügen müssen, erfasst die URL, die für das Hashing verwendet wird.

1

{% capture url %}{{projectUrl}}?data={{base64JsonPayload}}{% endcapture %}

Anschließend müssen Sie mit diesem Hash und Ihrem Project Secret eine Signatur generieren. Dazu fügen Sie ein drittes Code-Snippet ein:

1

{% capture sig %}{{url | hmac_sha1: "Project_Secret"}}{% endcapture %}

Hängen Sie schließlich die Signatur mit dem fünften Code-Snippet an die vollständige URL an:

1

{% capture longURL %}{{projectUrl}}?data={{base64JsonPayload}}&sig={{sig}}{% endcapture %}

Schritt 4: URL ausgeben

Stellen Sie zum Schluss sicher, dass Sie Ihre finale URL aufrufen, damit Ihre SmartPass-URL in Ihrer Nachricht ausgegeben wird.

1

{{longURL}}

Sie haben nun einen Content-Block erstellt, der etwa so aussieht:

1
2
3
4
5
6
7
8
9

{% capture base64JsonPayload %}{{passData|base64_encode}}{% endcapture %}

{% capture url %}{{projectUrl}}?data={{base64JsonPayload}}{% endcapture %}

{% capture sig %}{{url | hmac_sha1: "Project_Secret"}}{% endcapture %}

{% capture longURL %}{{projectUrl}}?data={{base64JsonPayload}}&sig={{sig}}&utm_source=braze&utm_campaign={{campaign.${name}}}{% endcapture %}{% capture longURL %}{{longURL | url_encode}}{% endcapture %}

{{longURL}}

In diesem Beispiel wurden UTM-Parameter hinzugefügt, um die Quelle dieser Installationen auf Braze und diese Campaign zurückzuführen.

Tipp

Denken Sie daran, Ihren Content-Block zu speichern, bevor Sie die Seite verlassen.

Schritt 5: Alles zusammenführen

Sobald dieser Content-Block erstellt ist, können Sie ihn in Zukunft wiederverwenden.

Möglicherweise fällt Ihnen auf, dass im Beispiel-Content-Block zwei Variablen undefiniert bleiben.
{{passData}} – Ihre JSON-Payload mit den Pass-Daten, die Sie in Schritt 1 definiert haben
{{projectUrl}} – Die URL Ihres Projekts oder Programms, die Sie im Tab „Distribution“ Ihres PassKit-Projekts finden.

Das ist beabsichtigt und unterstützt die Wiederverwendbarkeit des Content-Blocks. Da auf diese Variablen im Content-Block nur verwiesen wird, sie dort aber nicht erstellt werden, können sie sich ändern, ohne dass der Content-Block neu erstellt werden muss.

Vielleicht möchten Sie zum Beispiel das Einführungsangebot ändern, um mehr Startpunkte in Ihrem Kundenbindungs-Programm zu vergeben, oder Sie möchten eine zweite Mitgliedskarte oder einen weiteren Coupon erstellen. Für diese Szenarien wären unterschiedliche PassKit-projectURLs oder unterschiedliche Pass-Payloads erforderlich, die Sie pro Campaign in Braze definieren würden.

Nachrichtentext verfassen

Erfassen Sie beide Variablen in Ihrem Nachrichtentext und rufen Sie anschließend Ihren Content-Block auf. Erfassen Sie Ihre minimierte JSON-Payload aus Schritt 1:

Projekt-URL zuweisen

1

{% assign projectUrl = "https://pub1.pskt.io/c/ww0jir" %}

JSON erfassen

1

{% capture passData %}{"members.member.externalId": "{{${user_id}}}","members.member.points": "100","members.tier.name": "current_customer","person.displayName": "{{${first_name}}} {{${last_name}}}","person.externalId": "{{${user_id}}}","universal.expiryDate": "{{ "now" | date: "%s" | plus: 31622400 | date: "%FT%TZ" }}"}{% endcapture %}

Auf den soeben erstellten Content-Block verweisen

1

{{content_block.${passkit_SmartPass_url}}}

Ihr Nachrichtentext sollte etwa so aussehen:

Die ausgegebene URL für das Beispiel lautet:

Die ausgegebene URL ist lang. Das liegt daran, dass sie alle Pass-Daten enthält und erstklassige Sicherheitsmechanismen nutzt, um die Datenintegrität zu gewährleisten und Manipulationen durch Änderungen an der URL zu verhindern. Wenn Sie diese URL per SMS verteilen, empfiehlt es sich, sie mit einem Link-Kürzungsdienst wie bit.ly zu kürzen. Dies lässt sich über einen Connected-Content-Aufruf an einen bit.ly-Endpunkt umsetzen.

Pass mit dem PassKit-Webhook aktualisieren

In Braze können Sie eine Webhook-Kampagne oder einen Webhook innerhalb eines Canvas einrichten, um einen bestehenden Pass auf Grundlage des Verhaltens Ihrer Nutzer:innen zu aktualisieren. Unter den folgenden Links finden Sie Informationen zu nützlichen PassKit-Endpunkten.

• Mitgliedschaftsprojekte
• Coupon-Projekte
• Flugprojekte

Payload-Parameter

Bevor Sie beginnen, finden Sie hier die gängigen JSON-Payload-Parameter, die Sie in Ihre Webhooks zum Erstellen und Aktualisieren an PassKit aufnehmen können.

Schritt 1: Erstellen Sie Ihr Braze-Webhook-Template

Um ein PassKit-Webhook-Template für zukünftige Kampagnen oder Canvases zu erstellen, gehen Sie im Braze-Dashboard zum Bereich Templates und Medien. Wenn Sie eine einmalige PassKit-Webhook-Kampagne erstellen oder ein bestehendes Template verwenden möchten, wählen Sie beim Erstellen einer neuen Kampagne in Braze Webhook aus.

Nachdem Sie das PassKit-Webhook-Template ausgewählt haben, sollten Sie Folgendes sehen:

• Webhook-URL: https://api-pub1.passkit.io/coupon/singleUse/coupon
• Anfragetext: Rohtext

Anfrage-Header und Methode

PassKit benötigt für die Autorisierung einen HTTP Header, der Ihren Base64-kodierten PassKit-API-Schlüssel enthält. Folgendes ist bereits als Schlüssel-Wert-Paar im Template enthalten, aber im Tab Einstellungen müssen Sie <PASSKIT_LONG_LIVED_TOKEN> durch Ihren PassKit-Token ersetzen. Um Ihren Token abzurufen, navigieren Sie zu Ihrem PassKit-Projekt bzw. -Programm und dort zu Settings > Integrations > Long Lived Token.

• HTTP-Methode: PUT
• Anfrage-Header:
  • Authorization: Bearer <PASSKIT_LONG_LIVED_TOKEN>
  • Content-Type: application/json

Anfragetext

Um den Webhook einzurichten, füllen Sie die Details des neuen Events im Anfragetext aus, einschließlich der für Ihren Anwendungsfall erforderlichen Payload-Parameter:

1
2
3
4
5

{
  "externalId": "{{${user_id}}}",
  "campaignId": " 2xa1lRy8dBz4eEElBfmIz8",
  "expiryDate": "2020-05-10T00:00:00Z"
}

Schritt 2: Vorschau Ihrer Anfrage

Ihr Rohtext wird automatisch hervorgehoben, wenn es sich um ein zutreffendes Braze-Tag handelt.

Sehen Sie sich Ihre Anfrage im Panel Vorschau an oder navigieren Sie zum Tab Test, wo Sie zufällige Nutzer:innen oder bestehende Nutzer:innen auswählen oder eigene anpassen können, um Ihren Webhook zu testen.

Wichtig

Denken Sie daran, Ihr Template zu speichern, bevor Sie die Seite verlassen!
Aktualisierte Webhook-Templates finden Sie in der Liste Gespeicherte Webhook-Templates, wenn Sie eine neue Webhook-Kampagne erstellen.

Pass-Details über Connected-Content abrufen

Zusätzlich zum Erstellen und Aktualisieren von Pässen können Sie auch die Pass-Metadaten Ihrer Nutzer:innen über Braze Connected-Content abrufen, um personalisierte Pass-Details in Ihre Messaging-Kampagnen einzubinden.

PassKit Connected-Content-Aufruf

1
2
3

{% connected_content  https://api-pub1.passkit.io/coupon/singleUse/coupon/externalId/{{${user_id}}} :headers {"Authorization": "Bearer <PASSKIT_LONG_LIVED_TOKEN>","Content-Type": "application/json"} :save passes %}

{{passes.status}}

Liquid-Beispielantworten

• passes redemptiondetails
• passes status

1
2
3
4
5
6
7
8
9
10
11

{
    "redemptionDate": null,
    "redemptionCode": "",
    "lat": 0,
    "lon": 0,
    "alt": 0,
    "redemptionSource": "",
    "redemptionReference": "",
    "transactionReference": "",
    "transactionAmount": 0
}

1

UNREDEEMED