PassKit

PassKit te permite ampliar tu alcance móvil integrando pases de Apple Wallet y Google Pay en la experiencia de tus clientes. Crea, gestiona, distribuye y analiza fácilmente el rendimiento de cupones digitales, tarjetas de fidelización, carnés de socio, entradas y mucho más, sin que tus clientes necesiten otra aplicación.

Esta integración está mantenida por Passkit.

Acerca de la integración

La integración de Braze y PassKit te permite aumentar y medir la participación de tus campañas en línea entregando al instante pases personalizados de Apple Wallet y Google Pay. Luego puedes analizar el uso y realizar ajustes en tiempo real para aumentar el tráfico en tienda desencadenando mensajes basados en la ubicación y actualizaciones dinámicas y personalizadas en la billetera móvil de tu cliente.

Requisitos previos

Integración

Para enriquecer aún más las experiencias de billetera móvil de tus clientes, desde el panel de PassKit, puedes optar por enviar datos a Braze a través del endpoint /users/track de Braze.

Algunos ejemplos de datos que puedes compartir desde PassKit incluyen:

• Pase creado: cuando un cliente hace clic en un enlace de pase y se le muestra un pase por primera vez.
• Instalaciones de pase: cuando el cliente agrega y guarda el pase en su aplicación de billetera.
• Actualizaciones de pase: cuando se actualiza un pase.
• Eliminación de pase: cuando un cliente elimina el pase de su aplicación de billetera.

Una vez que los datos se envían a Braze, puedes crear audiencias, personalizar contenido a través de Liquid y desencadenar Campaigns o Canvas después de que se hayan realizado estas acciones.

Conectar Passkit con Braze

Para pasar datos de PassKit, asegúrate de haber configurado tu ID externo de Braze como el externalId de PassKit.

1. En Settings, en Integrations de tu proyecto o programa de pases de PassKit, haz clic en Connect en la pestaña Braze.
   
   
   
2. Completa tu clave de API de Braze, la URL del endpoint y proporciona un nombre para tu conector.
   
   
3. Alterna Enable Integration y los eventos que quieras en Braze para desencadenar o personalizar tus mensajes.
   

Crear un pase con un enlace SmartPass

Dentro de Braze, puedes configurar un enlace SmartPass para generar una URL única que tus clientes puedan usar para instalar su pase en Android o iOS. Para hacerlo, debes definir una carga útil de datos SmartPass cifrada que pueda llamarse desde un bloque de contenido de Braze. Este bloque de contenido puede reutilizarse para futuros pases y cupones. Lo siguiente se utiliza durante tu integración:

• URL de PassKit: Tu URL de PassKit es una URL única para tu programa PassKit.
  Cada programa tiene una URL única, y puedes encontrarla en la pestaña Distribution de tu programa o proyecto de PassKit (por ejemplo, https://pub1.pskt.io/c/ww0jir).
  
  
• Secreto de PassKit: Junto con la URL, debes tener disponible la clave de PassKit para este programa.
  Puedes encontrarla en la misma página que tu URL de PassKit.
  
  
• ID del programa (o proyecto): El ID de tu programa PassKit es necesario para crear la URL de SmartPass.
  Puedes encontrarlo en la pestaña Settings de tu proyecto o programa.

Para más información sobre cómo crear enlaces SmartPass cifrados, consulta este artículo de PassKit.

Paso 1: Define la carga útil de datos de tu pase

Primero, debes definir la carga útil del cupón o de la membresía.

Hay muchos componentes diferentes que puedes incluir en tu carga útil, pero aquí hay dos importantes a tener en cuenta:

Para una lista completa de los campos disponibles, sus tipos y descripciones útiles, consulta la documentación de PassKit en GitHub.

Ejemplo de carga útil

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" }}"
}

Paso 2: Crea y codifica una variable de carga útil indefinida

Crea y nombra un nuevo bloque de contenido navegando a Content > Content Block dentro del panel de Braze.

Selecciona Create Content Block para comenzar.

A continuación, debes definir tu etiqueta Liquid del bloque de contenido. Después de guardar este bloque de contenido, esta etiqueta de Liquid puede referenciarse al componer mensajes. En este ejemplo, hemos asignado la etiqueta de Liquid como {{content_blocks.${passKit_SmartPass_url}}}.

Dentro de este bloque de contenido, no incluiremos directamente la carga útil, sino que la referenciaremos en una variable {{passData}}. El primer fragmento de código que debes agregar a tu bloque de contenido captura una codificación Base64 de la variable {{passData}}.

1

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

Paso 3: Crea tu firma de cifrado usando un hash SHA1 HMAC

A continuación, crearás tu firma de cifrado usando un hash SHA1 HMAC de la URL del proyecto y la carga útil.

El segundo fragmento de código que debes agregar a tu bloque de contenido captura la URL que se usará para el hash.

1

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

Después, debes generar una firma usando este hash y tu Project Secret. Esto puede hacerse incluyendo un tercer fragmento de código:

1

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

Finalmente, añade la firma a la URL completa usando el quinto fragmento de código:

1

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

Paso 4: Imprime tu URL

Por último, asegúrate de llamar a tu URL final para que imprima tu URL de SmartPass dentro de tu mensaje.

1

{{longURL}}

En este punto, habrás creado un bloque de contenido que se ve algo así:

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}}

En este ejemplo, se han añadido parámetros UTM para rastrear el origen de estas instalaciones de vuelta a Braze y esta Campaign.

Consejo

Recuerda guardar tu bloque de contenido antes de abandonar la página.

Paso 5: Poniéndolo todo junto

Una vez que se ha creado este bloque de contenido, puede reutilizarse en el futuro.

Puedes notar que hay dos variables sin definir en el ejemplo del bloque de contenido.
{{passData}} - Tu carga útil de datos del pase en JSON definida en el paso 1
{{projectUrl}} - La URL de tu proyecto o programa que encuentras en la pestaña de distribución de tu proyecto de Passkit.

Esta decisión es intencional y apoya la reutilización del bloque de contenido. Dado que estas variables solo se referencian, no se crean dentro del bloque de contenido, pueden cambiar sin necesidad de rehacer el bloque de contenido.

Por ejemplo, quizás quieras cambiar la oferta introductoria para incluir más puntos iniciales en tu programa de fidelización, o tal vez quieras crear una tarjeta de membresía o cupón secundario. Estos escenarios requerirían diferentes projectURLs de Passkit o diferentes cargas útiles de pase, que definirías por Campaign en Braze.

Composición del cuerpo del mensaje

Querrás capturar ambas variables en el cuerpo de tu mensaje y luego llamar a tu bloque de contenido. Captura tu carga útil JSON minificada del paso 1:

Asignar la URL del proyecto

1

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

Capturar el JSON

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 %}

Referenciar el bloque de contenido que acabas de crear

1

{{content_block.${passkit_SmartPass_url}}}

El cuerpo de tu mensaje debería verse algo así:

La URL de salida de ejemplo es:

La URL de salida será larga. La razón de esto es que contiene todos los datos del pase e incorpora seguridad de primer nivel para garantizar la integridad de los datos y evitar alteraciones mediante la modificación de la URL. Si usas SMS para distribuir esta URL, es posible que quieras ejecutarla a través de un proceso de acortamiento de enlaces como bit.ly. Esto puede hacerse a través de una llamada de contenido conectado a un endpoint de bit.ly.

Actualizar un pase utilizando el webhook de PassKit

Dentro de Braze, puedes configurar una campaña de webhook o un webhook dentro de un Canvas para actualizar un pase existente en función del comportamiento de tu usuario. Consulta los siguientes enlaces para obtener información sobre los endpoints útiles de PassKit.

• Proyectos de miembros
• Proyectos de cupones
• Proyectos de vuelos

Parámetros de la carga útil

Antes de comenzar, estos son los parámetros comunes de la carga útil JSON que puedes incluir en tus webhooks de creación y actualización hacia PassKit.

Paso 1: Crea tu plantilla de webhook en Braze

Para crear una plantilla de webhook de PassKit y utilizarla en futuras campañas o Canvas, navega a la sección Plantillas y medios en el panel de Braze. Si deseas crear una campaña de webhook de PassKit de un solo uso o utilizar una plantilla existente, selecciona Webhook en Braze al crear una nueva campaña.

Una vez que hayas seleccionado la plantilla de webhook de PassKit, deberías ver lo siguiente:

• URL del webhook: https://api-pub1.passkit.io/coupon/singleUse/coupon
• Cuerpo de la solicitud: Texto sin formato

Encabezados de solicitud y método

PassKit requiere un HTTP Header para la autorización que incluya tu clave de API de PassKit codificada en base 64. Lo siguiente ya estará incluido dentro de la plantilla como un par clave-valor, pero en la pestaña Configuración, debes reemplazar <PASSKIT_LONG_LIVED_TOKEN> con tu token de PassKit. Para recuperar tu token, navega a tu proyecto/programa de PassKit, ve a Settings > Integrations > Long Lived Token.

• Método HTTP: PUT
• Encabezado de solicitud:
  • Authorization: Bearer <PASSKIT_LONG_LIVED_TOKEN>
  • Content-Type: application/json

Cuerpo de la solicitud

Para configurar el webhook, completa los detalles del nuevo evento dentro del cuerpo de la solicitud, incluyendo los parámetros de la carga útil necesarios para tu caso de uso:

1
2
3
4
5

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

Paso 2: Previsualiza tu solicitud

Tu texto sin formato resaltará automáticamente si se trata de una etiqueta de Braze aplicable.

Previsualiza tu solicitud en el panel Vista previa o navega a la pestaña Prueba, donde puedes seleccionar un usuario aleatorio, un usuario existente o personalizar el tuyo propio para probar tu webhook.

Importante

Recuerda guardar tu plantilla antes de salir de la página.
Las plantillas de webhook actualizadas se pueden encontrar en la lista Plantillas de webhook guardadas al crear una nueva campaña de webhook.

Recuperar detalles del pase mediante contenido conectado

Además de crear y actualizar pases, también puedes recuperar los metadatos de los pases de tus usuarios a través del contenido conectado de Braze para incorporar detalles personalizados de pases en tus campañas de mensajería.

Llamada de contenido conectado de PassKit

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}}

Ejemplos de respuestas con Liquid

• 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