PassKit

A PassKit permite ampliar o alcance da sua marca em dispositivos móveis por meio da integração de passes da Apple Wallet e do Google Pay às experiências dos clientes. Crie, gerencie, distribua e analise facilmente o desempenho de cupons digitais, cartões de fidelidade, cartões de associação, tickets e muito mais, sem que seus clientes precisem de outro app.

Essa integração é mantida pela Passkit.

Sobre a integração

A integração da Braze com o PassKit permite aumentar e medir o engajamento das suas campanhas online, entregando instantaneamente passes personalizados do Apple Wallet e do Google Pay. Depois, você pode analisar o uso e fazer ajustes em tempo real para aumentar o tráfego nas lojas, disparando mensagens baseadas em localização e atualizações dinâmicas e personalizadas na carteira digital do seu cliente.

Pré-requisitos

Integração

Para enriquecer ainda mais as experiências de carteira digital dos seus clientes, a partir do dashboard do PassKit, você pode optar por enviar dados para a Braze por meio do endpoint /users/track da Braze.

Exemplos de dados para compartilhar do PassKit incluem:

• Passe criado: quando um cliente clica em um link de passe e visualiza o passe pela primeira vez.
• Instalações de passe: quando o cliente adiciona e salva o passe no app de carteira.
• Atualizações de passe: quando um passe é atualizado.
• Exclusão de passe: quando um cliente exclui o passe do app de carteira.

Depois que os dados são enviados para a Braze, você pode criar públicos, personalizar conteúdo via Liquid e disparar Campaigns ou Canvas após essas ações terem sido realizadas.

Conectar o Passkit à Braze

Para transmitir dados do PassKit, verifique se você definiu seu ID externo da Braze como o externalId do PassKit.

1. Em Settings, na seção Integrations do seu projeto ou programa de passe do PassKit, clique em Connect na guia Braze.
   
   
   
2. Preencha sua chave de API da Braze, a URL do endpoint e forneça um nome para o seu conector.
   
   
3. Ative a opção Enable Integration e selecione os eventos que você deseja que a Braze dispare ou use para personalizar suas mensagens.
   

Criar passe usando um link SmartPass

Na Braze, você pode configurar um link SmartPass para gerar uma URL exclusiva para que seus clientes instalem o passe no Android ou iOS. Para isso, é necessário definir uma carga útil de dados SmartPass criptografada que pode ser chamada a partir de um bloco de conteúdo da Braze. Esse bloco de conteúdo pode ser reutilizado para passes e cupons futuros. Os seguintes itens são usados durante a integração:

• URL do PassKit: a URL do PassKit é uma URL exclusiva para o seu programa PassKit.
  Cada programa tem uma URL exclusiva, e você pode encontrá-la na guia Distribution do seu programa ou projeto PassKit. (por exemplo, https://pub1.pskt.io/c/ww0jir)
  
  
• Segredo do PassKit: junto com a URL, você precisa ter a chave do PassKit para este programa disponível.
  Ela pode ser encontrada na mesma página da URL do PassKit.
  
  
• ID do programa (ou projeto): o ID do programa PassKit é necessário para criar a URL SmartPass.
  Você pode encontrá-lo na guia Settings do seu projeto ou programa.

Para saber mais sobre a criação de links SmartPass criptografados, confira este artigo do PassKit.

Etapa 1: Definir a carga útil de dados do passe

Primeiro, você precisa definir a carga útil do cupom ou da associação.

Existem muitos componentes diferentes que podem ser incluídos na carga útil, mas aqui estão dois importantes a serem observados:

Para uma lista completa dos campos disponíveis, seus tipos e descrições úteis, confira a documentação do PassKit no GitHub.

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

Etapa 2: Criar e codificar uma variável de carga útil indefinida

Crie e nomeie um novo bloco de conteúdo navegando até Content > Content Block no dashboard da Braze.

Selecione Create Content Block para começar.

Em seguida, você deve definir sua Content Block Liquid Tag. Após salvar este bloco de conteúdo, essa Liquid tag pode ser referenciada ao compor mensagens. Neste exemplo, atribuímos a Liquid tag como {{content_blocks.${passKit_SmartPass_url}}}.

Dentro deste bloco de conteúdo, não incluiremos diretamente a carga útil, mas a referenciaremos em uma variável {{passData}}. O primeiro trecho de código que você deve adicionar ao seu bloco de conteúdo captura uma codificação Base64 da variável {{passData}}.

1

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

Etapa 3: Criar sua assinatura de criptografia usando um hash SHA1 HMAC

Em seguida, você criará sua assinatura de criptografia usando um hash SHA1 HMAC da URL do projeto e da carga útil.

O segundo trecho de código que você deve adicionar ao seu bloco de conteúdo captura a URL a ser usada para o hashing.

1

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

Em seguida, você deve gerar uma assinatura usando esse hash e seu Project Secret. Isso pode ser feito incluindo um terceiro trecho de código:

1

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

Por fim, anexe a assinatura à URL completa usando o quinto trecho de código:

1

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

Etapa 4: Imprimir sua URL

Por último, certifique-se de chamar sua URL final para que ela imprima a URL SmartPass dentro da sua mensagem.

1

{{longURL}}

Neste ponto, você criou um bloco de conteúdo parecido com isto:

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

Neste exemplo, parâmetros UTM foram adicionados para rastrear a origem dessas instalações de volta à Braze e a esta Campaign.

Dica

Lembre-se de salvar seu bloco de conteúdo antes de sair da página.

Etapa 5: Juntando tudo

Depois que este bloco de conteúdo for criado, ele poderá ser reutilizado no futuro.

Você pode notar que há duas variáveis indefinidas no exemplo de bloco de conteúdo.
{{passData}} - Sua carga útil de dados JSON do passe definida na etapa 1
{{projectUrl}} - A URL do seu projeto ou programa, que você encontra na guia de distribuição do seu projeto Passkit.

Essa decisão é proposital e favorece a reutilização do bloco de conteúdo. Como essas variáveis são apenas referenciadas, não criadas dentro do bloco de conteúdo, elas podem ser alteradas sem precisar refazer o bloco de conteúdo.

Por exemplo, talvez você queira alterar a oferta introdutória para incluir mais pontos iniciais no seu programa de fidelidade, ou talvez queira criar um cartão de associado secundário ou cupom. Esses cenários exigiriam diferentes projectURLs do Passkit ou diferentes cargas úteis de passe, que você definiria por Campaign na Braze.

Compor o corpo da mensagem

Você vai querer capturar ambas as variáveis no corpo da sua mensagem e então chamar seu bloco de conteúdo. Capture sua carga útil JSON minificada da etapa 1:

Atribuir a URL do projeto

1

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

Capturar o 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 o bloco de conteúdo que você acabou de criar

1

{{content_block.${passkit_SmartPass_url}}}

O corpo da sua mensagem deve ficar parecido com isto:

A URL de saída do exemplo é:

A URL de saída será longa. Isso acontece porque ela contém todos os dados do passe e incorpora segurança de primeiro nível para garantir a integridade dos dados e evitar adulteração por modificação da URL. Se você estiver usando SMS para distribuir essa URL, pode ser interessante passá-la por um processo de encurtamento de link como o bit.ly. Isso pode ser feito por meio de uma chamada de Connected Content para um endpoint do bit.ly.

Atualizar passe usando o webhook do PassKit

Na Braze, você pode configurar uma campanha de webhook ou um webhook dentro de um Canvas para atualizar um passe existente com base no comportamento do seu usuário. Confira os links a seguir para obter informações sobre endpoints úteis do PassKit.

• Projetos de membros
• Projetos de cupons
• Projetos de voos

Parâmetros da carga útil

Antes de começar, veja os parâmetros comuns de carga útil JSON que você pode incluir nos seus webhooks de criação e atualização para o PassKit.

Etapa 1: Crie seu modelo de webhook da Braze

Para criar um modelo de webhook do PassKit para usar em futuras campanhas ou Canvas, navegue até a seção Modelos e mídias no dashboard da Braze. Se você quiser criar uma campanha de webhook avulsa do PassKit ou usar um modelo existente, selecione Webhook na Braze ao criar uma nova campanha.

Depois de selecionar o modelo de webhook do PassKit, você verá o seguinte:

• URL do webhook: https://api-pub1.passkit.io/coupon/singleUse/coupon
• Corpo da solicitação: Raw Text

Cabeçalhos e método da solicitação

O PassKit requer um HTTP Header para autorização que inclua sua chave de API do PassKit codificada em base 64. O seguinte já estará incluído no modelo como um par chave-valor, mas na guia Settings, você deve substituir o <PASSKIT_LONG_LIVED_TOKEN> pelo seu token do PassKit. Para recuperar seu token, navegue até o seu projeto/programa do PassKit, acesse Settings > Integrations > Long Lived Token.

• Método HTTP: PUT
• Cabeçalho da solicitação:
  • Authorization: Bearer <PASSKIT_LONG_LIVED_TOKEN>
  • Content-Type: application/json

Corpo da solicitação

Para configurar o webhook, preencha os detalhes do novo evento no corpo da solicitação, incluindo os parâmetros de carga útil necessários para o seu caso de uso:

1
2
3
4
5

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

Etapa 2: Visualize sua solicitação

O texto bruto destacará automaticamente se for uma tag da Braze aplicável.

Visualize sua solicitação no painel Prévia ou navegue até a guia Teste, onde você pode selecionar um usuário aleatório, um usuário existente ou personalizar o seu próprio para testar seu webhook.

Importante

Lembre-se de salvar seu modelo antes de sair da página!
Os modelos de webhook atualizados podem ser encontrados na lista Saved Webhook Templates ao criar uma nova campanha de webhook.

Recuperar detalhes do passe via Connected Content

Além de criar e atualizar passes, você também pode recuperar os metadados dos passes dos seus usuários via Connected Content da Braze para incorporar detalhes personalizados dos passes nas suas campanhas de mensagens.

Chamada de Connected Content do 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}}

Exemplos de respostas 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