Überblick
Im Passinstance-Dashboard erscheinen Multi-Pass-Projekte (PassProject-Modell, verwaltet vom Projects API unter /api/v1/pass-projects und dem Alias /api/v1/wallet-experiences) im Bereich Wallet Experiences (/wallet-experiences, gegliedert in die Arbeitsbereichs-Tabs Overview, Cards, Audience, Automations, Distribution, Analytics und Settings). Ein Projekt verbindet eine Hauptvorlage (mainTemplateId) mit verknüpften Begleitvorlagen zu durchgängigen Kundenreisen und unterstützt Apple Wallet Pass Bundles (.pkpasses) (Pass.bundleId / pass bundle) sowie regelbasierte Segment-Automatisierungen.
Systemarchitektur: Pass-Projekte, .pkpasses-Bündelung & Segment-Trigger
Kernmodelle & Vorlagenrollen (PassProjectTemplateRole)
Jedes PassProject verknüpft eine mainTemplateId (Rolle PRIMARY direkt am Projekt) mit angehängten Begleitvorlagen (PassProjectTemplate, schreibbare Rollen LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):
PassProjectTemplateRole | Speicherort | Fachliche Aufgabe im Projekt |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | Die zentrale Ankerkarte (z. B. Saisonkarte, Hotel-Zimmerschlüssel oder Treuekarte), deren externalId und Kundenattribute das Erlebnis steuern. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Begleitvorlagen (z. B. VIP-Backstage-Zugang, Getränkecoupon, Parkausweis), die beim Download gebündelt oder dynamisch über Segment-/Automationsregeln ausgegeben werden. |
PRIVACY_MODE | PassProjectTemplate.role | Eine reduzierte Alternativvorlage, auf die automatisch umgeschaltet wird, sobald eine Person dem Tracking oder der Personalisierung widerspricht. |
INACTIVE | PassProjectTemplate.role | Verknüpfte Vorlage, die vorübergehend aus neuen Bündel-Downloads ausgeschlossen wird, ohne die Verknüpfungshistorie zu lösen. |
Apple Wallet Pass Bundles (.pkpasses) & Pass.bundleId
Wenn die Bündelung aktiviert ist (bundleOnDownload: true, maxBundleSize bis zu 10), verknüpft Passinstance gemeinsam ausgegebene Begleitpässe über eine geteilte Pass.bundleId (Fremdschlüssel bundleId auf pass bundle):
-
Apple Wallet (
.pkpasses-Archiv): Erzeugt durchPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*oderPOST /api/v1/pass-projects/:id/download-bundle). Verpackt bis zu 10 signierte.pkpass-Dateien (request payload: 2–10 Pässe;request payload: 1–10 Pässe) unter dem MIME-Typapplication/vnd.apple.pkpasses, sodass iOS den Dialog Alle hinzufügen anzeigt. -
Google Wallet Multi-Pass-Abruf: Stellt koordinierte Save-URLs und Bündel-Links bereit (
GET /api/v1/bundles/:id/google-wallet-link,PassProjectIssuanceProvider:APPLE\|GOOGLE,PassProjectIssuanceStatus:PENDING->VALIDATING->CREATING_PASSES->READY\|PARTIALLY_READY\|FAILED).
Wichtig: Apple iOS setzt eine harte Obergrenze von 10
.pkpass-Dateien innerhalb eines einzigen.pkpasses-Archivs (maxBundleSize <= 10). Jede in einem Bündel enthaltene Vorlage muss mit einem gültigen Apple Pass Type ID-Zertifikat veröffentlicht sein.
Zielgruppensegmente (PassProjectSegment) & Automation Flows
Projekte integrieren direkt mit PassProjectSegment und AutomationFlow, um dynamische Multi-Pass-Journeys ohne externen Webhook-Glue-Code zu steuern:
-
1
Dynamische Segmentauswertung: Definieren Sie Filterregeln über
Pass.attributes(z. B.attributes.spendTotal >= 500) und werten Sie diese überPOST /api/v1/pass-projects/:id/segments/:segmentId/evaluateaus. -
2
Automatisierte Begleitpass-Ausgabe: Sobald ein Hauptpass in ein Segment eintritt, gibt ein verknüpfter
AutomationFlowautomatisch einen Begleitpass (LINKED/VIP) aus und aktualisiert dessen Bündel- bzw. Download-Link. -
3
Datenschutz-Umschaltung (
PRIVACY_MODE): Wird die Einwilligung zur Personalisierung widerrufen, kann die Experience den Pass automatisch auf diePRIVACY_MODE-Vorlage umschalten.
REST-API-Referenz für Pass-Projekte (Projects API)
Alle Projekt-Endpunkte sind unter /api/v1/pass-projects (Alias /api/v1/wallet-experiences) eingebunden:
| HTTP-Methode & Endpunkt | Beschreibung |
|---|---|
GET /api/v1/pass-projects | Listet alle Wallet Experiences (Pass-Projekte) im aktiven Workspace auf. |
POST /api/v1/pass-projects | Erstellt ein neues PassProject mit request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Ruft Projektkonfiguration, verknüpfte Vorlagen, Bereitschaftsstatus und Segmente ab. |
PATCH /api/v1/pass-projects/:id | Aktualisiert Projektname, Beschreibung, mainTemplateId, bundleOnDownload, maxBundleSize oder slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Verknüpft eine Begleitvorlage (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Konfiguriert Bündel-Reihenfolge, Limits (maxBundleSize) und .pkpasses-Metadaten. |
POST /api/v1/pass-projects/:id/download-bundle | Erzeugt bzw. lädt das koordinierte .pkpasses-Bündelarchiv für einen Pass/eine Ausgabe herunter. |
GET /api/v1/pass-projects/bundle-passes/:passId | Listet alle über bundleId mit einer bestimmten passId verknüpften Begleitpässe auf. |
Beispiel: Multi-Pass-Projekt erstellen (request payload)
POST /api/v1/pass-projects Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Alpine Ski Resort - VIP Winter Package",
"description": "Season ski pass with aprés-ski voucher and privacy layout",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"slug": "alpine-vip-winter-2026"
}
HTTP-Antwort (201 Created)
{
"success": true,
"data": {
"id": "proj_01j9k8l7m6n5p4",
"name": "Alpine Ski Resort - VIP Winter Package",
"slug": "alpine-vip-winter-2026",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"createdAt": "2026-11-15T19:00:00.000Z"
},
"statusCode": 201
}
Lesen Sie Architektur des Pass-Bundlings für technische Paketierungsabläufe sowie Workflow-Konfiguration für projektübergreifende Automatisierungsregeln.
