Skip to content
Hilfecenter-Anleitung · Projekte & Organisation
3 Min. LesezeitGeprüft 2026-11-16

Projekte verwalten

Gruppieren Sie eine Hauptvorlage mit verknüpften Vorlagen zu Wallet Experiences, Bundles und segmentbasierten Wechseln.

In dieser Anleitung

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PASS-PROJEKT-BÜNDELUNG (.PKPASSES) & SEGMENT-AUTOMATION
STUFE 01 PASS-PROJEKT (PassProject & PassProjectTemplate)
PRIMARY (mainTemplateId): Haupt-Mitgliedschaft / Ticket / Bordkarte
LINKED / VIP / CUSTOM: Begleitender Lounge-Gutschein / Park-/Gala-Pass
PRIVACY_MODE / INACTIVE: Datenschutz-Layout oder pausierte Begleitkarte
STUFE 02A APPLE PASS BUNDLE (.pkpasses-ZIP)
Bündelt bis zu 10 signierte .pkpass
Dateien zu gemeinsamer Pass.bundleId
bundle grouping mode: AUTO | `MANUA
BundleStatus: ACTIVE | CANCELLED
STUFE 02B SEGMENT- & AUTOMATIONS-ORCHESTRATOR
Wertet PassProjectSegment-Regeln gegen Pass.attributes (GIN) aus | | - LöstAutomationFlow`-Aktio
Begleitpass ausgeben / Vorl. wech.

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):

PassProjectTemplateRoleSpeicherortFachliche Aufgabe im Projekt
PRIMARYPassProject.mainTemplateIdDie zentrale Ankerkarte (z. B. Saisonkarte, Hotel-Zimmerschlüssel oder Treuekarte), deren externalId und Kundenattribute das Erlebnis steuern.
LINKED / VIP / CUSTOMPassProjectTemplate.roleBegleitvorlagen (z. B. VIP-Backstage-Zugang, Getränkecoupon, Parkausweis), die beim Download gebündelt oder dynamisch über Segment-/Automationsregeln ausgegeben werden.
PRIVACY_MODEPassProjectTemplate.roleEine reduzierte Alternativvorlage, auf die automatisch umgeschaltet wird, sobald eine Person dem Tracking oder der Personalisierung widerspricht.
INACTIVEPassProjectTemplate.roleVerknü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 durch Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* oder POST /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-Typ application/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. 1
    Dynamische Segmentauswertung: Definieren Sie Filterregeln über Pass.attributes (z. B. attributes.spendTotal >= 500) und werten Sie diese über POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate aus.
  2. 2
    Automatisierte Begleitpass-Ausgabe: Sobald ein Hauptpass in ein Segment eintritt, gibt ein verknüpfter AutomationFlow automatisch einen Begleitpass (LINKED / VIP) aus und aktualisiert dessen Bündel- bzw. Download-Link.
  3. 3
    Datenschutz-Umschaltung (PRIVACY_MODE): Wird die Einwilligung zur Personalisierung widerrufen, kann die Experience den Pass automatisch auf die PRIVACY_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 & EndpunktBeschreibung
GET /api/v1/pass-projectsListet alle Wallet Experiences (Pass-Projekte) im aktiven Workspace auf.
POST /api/v1/pass-projectsErstellt ein neues PassProject mit request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idRuft Projektkonfiguration, verknüpfte Vorlagen, Bereitschaftsstatus und Segmente ab.
PATCH /api/v1/pass-projects/:idAktualisiert Projektname, Beschreibung, mainTemplateId, bundleOnDownload, maxBundleSize oder slug.
POST /api/v1/pass-projects/:id/templates/:templateIdVerknüpft eine Begleitvorlage (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleKonfiguriert Bündel-Reihenfolge, Limits (maxBundleSize) und .pkpasses-Metadaten.
POST /api/v1/pass-projects/:id/download-bundleErzeugt bzw. lädt das koordinierte .pkpasses-Bündelarchiv für einen Pass/eine Ausgabe herunter.
GET /api/v1/pass-projects/bundle-passes/:passIdListet 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

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)

JSON
{
  "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.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.