PassKit
PassKit을 사용하면 Apple Wallet 및 Google Pay 패스를 고객 경험에 통합하여 모바일 도달 범위를 확장할 수 있습니다. 디지털 쿠폰, 로열티 카드, 멤버십 카드, 티켓 등을 쉽게 생성, 관리, 배포하고 성능을 분석할 수 있으며, 고객이 별도의 앱을 설치할 필요가 없습니다.
이 통합은 Passkit에서 유지 관리합니다.
통합 정보
Braze와 PassKit 통합을 사용하면 커스텀 Apple Wallet 및 Google Pay 패스를 즉시 전달하여 온라인 Campaigns의 인게이지먼트를 높이고 측정할 수 있습니다. 그런 다음 사용량을 분석하고, 위치 기반 메시지와 고객의 모바일 지갑에 대한 개인화된 동적 업데이트를 트리거하여 실시간으로 조정함으로써 매장 방문객을 늘릴 수 있습니다.
필수 조건
| 요구 사항 | 설명 |
|---|---|
| PassKit 계정 | PassKit 계정과 PassKit 계정 매니저가 있어야 합니다. |
userDefinedID |
PassKit과 Braze 간에 사용자의 커스텀 이벤트와 커스텀 속성을 적절하게 업데이트하려면 Braze 외부 ID를 userDefinedID로 설정해야 합니다. 이 userDefinedID는 PassKit 엔드포인트에 API를 호출할 때 사용됩니다. |
| Braze REST API 키 | users.track 권한이 있는 Braze REST API 키입니다. Braze 대시보드의 설정 > API 키에서 생성할 수 있습니다. |
| Braze REST 엔드포인트 | REST 엔드포인트 URL입니다. 엔드포인트는 인스턴스의 Braze URL에 따라 달라집니다. |
통합
고객의 모바일 지갑 경험을 더욱 풍부하게 만들기 위해 PassKit 대시보드에서 Braze /users/track 엔드포인트를 통해 Braze로 데이터를 전달하도록 선택할 수 있습니다.
PassKit에서 공유할 수 있는 데이터의 예는 다음과 같습니다:
- 패스 생성: 고객이 패스 링크를 클릭하여 패스가 처음 표시될 때
- 패스 설치: 고객이 지갑 앱에 패스를 추가하고 저장할 때
- 패스 업데이트: 패스가 업데이트될 때
- 패스 삭제: 고객이 지갑 앱에서 패스를 삭제할 때
데이터가 Braze로 전달되면 이러한 작업이 수행된 후 오디언스를 구축하고, Liquid를 통해 콘텐츠를 개인화하고, Campaigns 또는 Canvases를 트리거할 수 있습니다.
Braze에 Passkit 연결하기
PassKit에서 데이터를 전달하려면 Braze 외부 ID를 PassKit의 externalId로 설정했는지 확인하세요.
- PassKit 패스 프로젝트 또는 프로그램의 설정에서 통합 아래에 있는 Braze 탭의 연결을 클릭합니다.

- Braze API 키와 엔드포인트 URL을 입력하고 커넥터 이름을 지정합니다.
- 통합 활성화를 토글하고, Braze에서 메시지를 트리거하거나 개인화하는 데 사용할 이벤트를 토글합니다.

SmartPass 링크로 패스 만들기
Braze에서 SmartPass 링크를 설정하면 고객이 Android 또는 iOS에 패스를 설치할 수 있는 고유 URL을 생성할 수 있습니다. 이렇게 하려면 Braze Content Block에서 호출할 수 있는 암호화된 SmartPass 데이터 페이로드를 정의해야 합니다. 이 Content Block은 이후 다른 패스와 쿠폰에도 재사용할 수 있습니다. 통합 과정에서는 다음 항목을 사용합니다.
- PassKit URL: PassKit URL은 PassKit 프로그램의 고유 URL입니다.
프로그램마다 고유한 URL이 있으며, PassKit 프로그램 또는 프로젝트의 배포 탭에서 확인할 수 있습니다. (예: https://pub1.pskt.io/c/ww0jir) - PassKit 시크릿: URL과 함께 이 프로그램의 PassKit 키도 준비해 두어야 합니다.
PassKit URL과 같은 페이지에서 확인할 수 있습니다. - 프로그램(또는 프로젝트) ID: SmartPass URL을 만들려면 PassKit 프로그램 ID가 필요합니다.
프로젝트 또는 프로그램의 설정 탭에서 확인할 수 있습니다.
암호화된 SmartPass 링크 생성에 대한 자세한 내용은 PassKit 웹사이트의 PassKit SmartPass 링크를 참조하세요.
1단계: 패스 데이터 페이로드 정의하기
먼저 쿠폰 또는 멤버 페이로드를 정의해야 합니다.
페이로드에 포함할 수 있는 구성 요소는 다양하지만, 특히 주목해야 할 두 가지는 다음과 같습니다.
| 구성 요소 | 필수 여부 | 유형 | 설명 |
|---|---|---|---|
person.externalId |
필수 | 문자열 | Braze 외부 ID로 설정합니다. PassKit에서 Braze로 돌아오는 콜백이 작동하는 데 매우 중요하며, 회사 사용자가 하나의 Campaign에서 여러 오퍼의 쿠폰을 보유할 수 있게 해줍니다. 고유성이 강제되지 않습니다. |
members.member.externalId |
선택 사항 | 문자열 | Braze 외부 ID로 설정합니다. 외부 ID를 사용하여 멤버십 패스를 업데이트할 수 있습니다. 이 필드를 설정하면 멤버십 프로그램 내에서 사용자의 고유성이 강제됩니다. |
사용 가능한 필드의 전체 목록과 유형, 유용한 설명은 PassKit GitHub 설명서를 참조하세요.
페이로드 예시
{
"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" }}"
}
2단계: 정의되지 않은 페이로드 변수 생성 및 인코딩하기
Braze 대시보드에서 Content > Content Block으로 이동하여 새 Content Block을 만들고 이름을 지정합니다.
Create Content Block을 선택하여 시작합니다.
다음으로 Content Block Liquid Tag를 정의해야 합니다. 이 Content Block을 저장한 후에는 메시지를 작성할 때 이 Liquid 태그를 참조할 수 있습니다. 이 예시에서는 Liquid 태그를 {{content_blocks.${passKit_SmartPass_url}}}로 지정했습니다.
이 Content Block에는 페이로드를 직접 포함하지 않고 {{passData}} 변수로 참조합니다. Content Block에 추가해야 하는 첫 번째 코드 스니펫은 {{passData}} 변수의 Base64 인코딩을 캡처합니다.
{% capture base64JsonPayload %}{{passDatapassData|base64_encode}}{% endcapture %}
3단계: SHA1 HMAC 해시로 암호화 서명 만들기
다음으로 프로젝트 URL과 페이로드의 SHA1 HMAC 해시를 사용하여 암호화 서명을 만듭니다.
Content Block에 추가해야 하는 두 번째 코드 스니펫은 해싱에 사용할 URL을 캡처합니다.
{% capture url %}{{projectUrl}}?data={{base64JsonPayload}}{% endcapture %}
그런 다음 이 해시와 Project Secret을 사용하여 서명을 생성해야 합니다. 세 번째 코드 스니펫을 포함하면 됩니다.
{% capture sig %}{{url | hmac_sha1: "Project_Secret"}}{% endcapture %}
마지막으로 다섯 번째 코드 스니펫을 사용하여 전체 URL에 서명을 추가합니다.
{% capture longURL %}{{projectUrl}}?data={{base64JsonPayload}}&sig={{sig}}{% endcapture %}
4단계: URL 출력하기
마지막으로 최종 URL을 호출하여 메시지 안에 SmartPass URL이 출력되도록 합니다.
{{longURL}}
여기까지 완료하면 다음과 같은 형태의 Content Block이 만들어집니다.
{% 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}}
이 예시에서는 이러한 설치의 출처가 Braze와 이 Campaign임을 추적할 수 있도록 UTM 파라미터를 추가했습니다.

페이지를 떠나기 전에 Content Block을 저장하는 것을 잊지 마세요.
5단계: 모두 합치기
이렇게 만든 Content Block은 향후 다시 재사용할 수 있습니다.
예시 Content Block에는 정의되지 않은 변수가 두 개 남아 있다는 것을 알 수 있습니다.
{{passData}} - 1단계에서 정의한 JSON 패스 데이터 페이로드
{{projectUrl}} - Passkit 프로젝트의 배포 탭에서 확인할 수 있는 프로젝트 또는 프로그램의 URL
이는 Content Block의 재사용성을 높이기 위한 의도적인 설계입니다. 이 변수들은 Content Block 내에서 생성되지 않고 참조만 되므로, Content Block을 다시 만들지 않고도 변수를 변경할 수 있습니다.
예를 들어 로열티 프로그램에서 초기 포인트를 더 많이 제공하도록 신규 가입 오퍼를 변경하거나, 보조 멤버 카드나 쿠폰을 만들고 싶을 수 있습니다. 이러한 경우에는 서로 다른 Passkit projectURLs 또는 서로 다른 패스 페이로드가 필요하며, 이는 Braze에서 Campaign별로 정의하면 됩니다.
메시지 본문 작성하기
메시지 본문에서 이 두 변수를 모두 캡처한 다음 Content Block을 호출해야 합니다. 1단계에서 만든 축소된 JSON 페이로드를 캡처합니다.
프로젝트 URL 할당하기
{% assign projectUrl = "https://pub1.pskt.io/c/ww0jir" %}
JSON 캡처하기
{% 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 %}
방금 만든 Content Block 참조하기
{{content_block.${passkit_SmartPass_url}}}
메시지 본문은 다음과 같은 형태가 됩니다.

예시의 출력 URL은 다음과 같습니다.

출력 URL은 길이가 깁니다. 모든 패스 데이터를 포함하고 있으며, 데이터 무결성을 보장하고 URL 수정을 통한 변조를 방지하기 위해 최고 수준의 보안을 적용하기 때문입니다. 단문 메시지 서비스(SMS)로 이 URL을 배포하는 경우 bit.ly와 같은 링크 단축 과정을 거치는 것이 좋습니다. 이는 bit.ly 엔드포인트에 연결된 콘텐츠 호출을 보내는 방식으로 수행할 수 있습니다.
PassKit 웹훅을 사용하여 패스 업데이트
Braze에서 웹훅 Campaign 또는 Canvas 내 웹훅을 설정하여 사용자 행동에 따라 기존 패스를 업데이트할 수 있습니다. 유용한 PassKit 엔드포인트에 대한 정보는 다음 링크를 참조하세요.
페이로드 파라미터
시작하기 전에, PassKit으로 보내는 생성 및 업데이트 웹훅에 포함할 수 있는 일반적인 JSON 페이로드 파라미터를 소개합니다.
| 데이터 | 유형 | 설명 |
|---|---|---|
externalId |
문자열 | 패스 레코드에 고유 ID를 추가하여 고유 고객 식별자(예: 멤버십 번호)를 사용하는 기존 시스템과의 호환성을 제공합니다. 패스 ID 대신 userDefinedId 및 campaignName을 통해 이 엔드포인트를 사용하여 패스 데이터를 가져올 수 있습니다. 이 값은 캠페인 내에서 고유해야 하며, 한 번 설정하면 변경할 수 없습니다.Braze 통합의 경우 Braze 외부 ID를 사용하는 것을 권장합니다: {{${user_id}}} |
campaignId (쿠폰) programId (멤버십) |
문자열 | PassKit에서 생성한 캠페인 또는 프로그램 템플릿의 ID입니다. 이 ID를 찾으려면 PassKit 패스 프로젝트의 Settings 탭으로 이동하세요. |
expiryDate |
IO8601 datetime | 패스 만료 날짜입니다. 만료 날짜가 지나면 패스가 자동으로 무효화됩니다(isVoided 참조). 이 값은 템플릿 및 캠페인 종료 날짜 값보다 우선합니다. |
status |
문자열 | 쿠폰의 현재 상태입니다(예: REDEEMED 또는 UNREDEEMED). |
1단계: Braze 웹훅 템플릿 만들기
향후 Campaigns 또는 Canvases에서 사용할 PassKit 웹훅 템플릿을 만들려면 Braze 대시보드의 템플릿 및 미디어 섹션으로 이동하세요. 일회성 PassKit 웹훅 Campaign을 만들거나 기존 템플릿을 사용하려면 새 Campaign을 만들 때 Braze에서 웹훅을 선택하세요.
PassKit 웹훅 템플릿을 선택하면 다음과 같은 내용이 표시됩니다.
- 웹훅 URL:
https://api-pub1.passkit.io/coupon/singleUse/coupon - 요청 본문: 원시 텍스트
요청 헤더 및 메서드
PassKit은 승인을 위해 Base64로 인코딩된 PassKit API 키가 포함된 HTTP Header를 요구합니다. 다음 항목은 이미 템플릿에 키-값 페어로 포함되어 있지만, 설정 탭에서 <PASSKIT_LONG_LIVED_TOKEN>을 PassKit 토큰으로 바꿔야 합니다. 토큰을 가져오려면 PassKit 프로젝트/프로그램으로 이동한 다음 Settings > Integrations > Long Lived Token으로 이동하세요.
- HTTP 메서드: PUT
- 요청 헤더:
- Authorization: Bearer
<PASSKIT_LONG_LIVED_TOKEN> - Content-Type: application/json
- Authorization: Bearer
요청 본문
웹훅을 설정하려면 사용 사례에 필요한 페이로드 파라미터를 포함하여 요청 본문에 새 이벤트 세부 정보를 입력하세요.
{
"externalId": "{{${user_id}}}",
"campaignId": " 2xa1lRy8dBz4eEElBfmIz8",
"expiryDate": "2020-05-10T00:00:00Z"
}
2단계: 요청 미리보기
원시 텍스트가 적용 가능한 Braze 태그인 경우 자동으로 강조 표시됩니다.
미리보기 패널에서 요청을 미리 보거나 테스트 탭으로 이동하여 무작위 사용자, 기존 사용자를 선택하거나 직접 사용자를 맞춤 설정하여 웹훅을 테스트할 수 있습니다.

Connected Content를 통해 패스 세부 정보 검색하기
패스를 생성하고 업데이트하는 것 외에도 Braze 연결된 콘텐츠를 통해 사용자의 패스 메타데이터를 검색할 수 있습니다. 이를 통해 개인화된 패스 세부 정보를 메시징 캠페인에 포함할 수 있습니다.
PassKit 연결된 콘텐츠 호출
{% 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 응답 예시
{
"redemptionDate": null,
"redemptionCode": "",
"lat": 0,
"lon": 0,
"alt": 0,
"redemptionSource": "",
"redemptionReference": "",
"transactionReference": "",
"transactionAmount": 0
}
UNREDEEMED