Personalisierte Wallet Passes per API ausstellen

Mit einer Wallet Pass API erstellt Ihr Backend für jeden Kunden einen eigenen Pass, mit Namen, Punktestand, Barcode und Standorten, und aktualisiert ihn, sobald sich Ihre Daten ändern. Sie gestalten die Vorlage einmal, senden pro Nutzer die persönlichen Werte und erhalten einen Installationslink für Apple Wallet oder einen Save-Link für Google Wallet zurück.

Persönliche Werte sind personenbezogene Daten. Bevor Sie Kundendaten aus CRM, Kassensystem oder Punktekonto an eine API übergeben, klären Sie deshalb, wo sie verarbeitet werden: Pushwoosh ist DSGVO-konform, nach ISO 27001:2022 und SOC 2 Type 2 zertifiziert und betreibt Rechenzentren in der EU und den USA. Halten Sie die Pass-Ausstellung in Ihrem Auftragsverarbeitungsvertrag (AVV) fest, bevor die erste Integration live geht.

Nicht jedes Team braucht die API. Die Beispiele nutzen die Wallet passes API von Pushwoosh, in der jeder Pass an eine User ID gebunden ist, die auch Ihre Push-Benachrichtigungen, E-Mails und Journeys steuert.

Wann die API den Builder schlägt

Der Builder ist das richtige Werkzeug, um einen Pass zu gestalten und kleine oder einmalige Versände abzuwickeln. Die API übernimmt, sobald Passes von Daten abhängen, die in Ihren eigenen Systemen liegen.

Sehen Sie sich die Journey-Spalte an, bevor Sie Code schreiben. Ist der Auslöser eine Kundenaktion, die Pushwoosh bereits erfasst, macht der Schritt Issue Wallet Pass (Wallet Pass ausstellen) in der Customer Journey eigenen Code oft überflüssig.

Vorlagen und persönliche Werte

Das Muster ist auf beiden Plattformen gleich. Die Vorlage enthält Layout, Branding und Feldstruktur. Die Werte pro Nutzer füllen sie bei der Ausstellung.

Persönliche Werte sind das, was sich von 1 Kunden zum nächsten ändert: Name, Mitgliedsnummer, Punkte, Status, Barcode-Wert, Ablaufdatum, nächste Filiale. Im E-Commerce ist das etwa der Kundenstatus im Onlineshop, im Automotive-Bereich das Fahrzeugmodell und der nächste Servicetermin. Alles andere kommt aus der Vorlage, sodass eine Designänderung für jeden neuen Pass gilt, ohne dass Sie Ihre Integration anfassen.

In einer Journey übernimmt der Schritt Issue Wallet Pass die Apple- und Google-Pass-Kampagnen (apple_campaign_id, google_campaign_id) und die personal_values, die er einsetzen soll. 1 Schritt kann beide Versionen für dieselbe User ID ausstellen.

Der Ablauf für Apple Wallet

Alles, was der Apple Pass Builder kann, steht auch in der Apple Wallet PassKit API zur Verfügung: Passes erstellen, aktualisieren, auflisten, herunterladen und löschen.

Eine typische Integration hat 4 Schritte.

Sie benötigen ein Pass-Type-ID-Zertifikat (.p12) pro Anwendung und ein Apple-Developer-Konto (99 US-Dollar pro Jahr). Die Einrichtung beschreibt die Dokumentation zur Konfiguration von iOS Wallet Passes.

Der Ablauf für Google Wallet

Die Google Wallet API deckt denselben Lebenszyklus für Google-Passes ab.

Sie benötigen eine Issuer ID aus der Google Pay & Wallet Console, zu deren Issuer das Service-Konto von Pushwoosh eingeladen ist, einmalig pro Anwendung eingerichtet. Die Einrichtung beschreibt die Dokumentation zur Konfiguration von Google Wallet.

Updates im großen Maßstab

Bei Updates spielt die API ihre Stärke aus. Ein Punktekonto oder Buchungssystem kann einen Pass in dem Moment aktualisieren, in dem sich ein Wert ändert, sodass die Karte im Wallet des Kunden Ihrer Datenquelle entspricht. Gerade vor Spitzen wie Black Friday oder dem Weihnachtsgeschäft lohnt es sich, diese Abläufe vorher mit echten Datenmengen zu testen.

3 Regeln halten große Update-Läufe sicher:

• Vom aktuellen Pass ausgehen. Apples Update erwartet das vollständige Pass-Objekt. Rufen Sie den Pass also ab und ändern Sie nur die Werte, die sich bewegt haben. Googles Update patcht das Objekt.
• Hinweise Feld für Feld festlegen. Bei Apple zeigen nur Felder mit einer Änderungsmeldung einen Hinweis auf dem Sperrbildschirm. Bei Google bittet notifyOnUpdate Google um einen eigenen Hinweis, der nur bei Kundenkarten, Eventtickets und Flugtickets erscheint, höchstens 3 pro Pass innerhalb von 24 Stunden. notifyMessage sendet Ihren eigenen Android-Benachrichtigungstext bei jedem Pass-Typ.
• Hinweise beim Pass belassen. Apple und Google erlauben Benachrichtigungen zum Pass, keine Werbung.

Codebeispiele

Beide APIs verwenden die Basis-URL https://apple-passkit.svc-nue.pushwoosh.com und Ihr Pushwoosh API Access Token im Header Authorization: Token <api-token>. Die folgenden Request-Bodys sind die Beispiele aus der API-Referenz.

Apple-Wallet-Pass erstellen: POST /api/pass/create. Die Antwort liefert die serialNumber des Passes.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Google-Wallet-Pass erstellen: POST /api/google/pass/create. Die Antwort liefert die serialNumber und einen saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Für ein Update senden Sie den neuen Inhalt mit der Seriennummer: POST /api/pass/update/{serialNumber} für Apple, POST /api/google/pass/update/{serialNumber} für Google.

Builder, API oder Journey: eine einfache Regel

Nutzen Sie den Builder zum Gestalten und Testen. Nutzen Sie den Journey-Schritt, wenn der Auslöser ein Kunden-Event ist, das bereits in Pushwoosh liegt, etwa eine Anmeldung oder ein Erstkauf. Nutzen Sie die API, wenn Auslöser oder Daten in Ihrem Backend liegen.

Die meisten Teams nutzen am Ende alle 3, und das ist in Ordnung: den Builder fürs Design, Journeys für Momente im Kundenlebenszyklus, die API für Punktestände und Status in Echtzeit. Der Fehler besteht darin, 1 Werkzeug die Aufgaben der anderen erledigen zu lassen.

Jeden Pass personalisieren mit Pushwoosh

Pushwoosh bietet einen visuellen Builder, einen Journey-Schritt und eine API für native Apple- und Google-Wallet-Passes, ohne separaten Pass-Anbieter dazwischen. Jeder Pass teilt sich eine User ID mit Ihrer Push-, In-App-, E-Mail- und SMS-Kommunikation, sodass 1 Datenbestand jeden Kanal steuert.

Personalisierung im großen Maßstab ist keine Frage von mehr Vorlagen. Es geht um 1 verlässliche Datenquelle, die jede Karte in jedem Wallet widerspiegelt.

FAQ