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 entre a Braze e a PassKit permite que você aumente e meça o engajamento de suas campanhas online, fornecendo instantaneamente passes personalizados da Apple Wallet e do Google Pay. Em seguida, é possível analisar o uso e fazer ajustes em tempo real para aumentar o tráfego na loja, disparando mensagens baseadas em localização e atualizações personalizadas e dinâmicas na carteira móvel do cliente.

Pré-requisitos

Integração

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

Exemplos de dados para compartilhar da PassKit incluem:

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

Depois que os dados são transmitidos para a Braze, você pode criar públicos, personalizar o conteúdo via Liquid e disparar Campaigns ou Canvas depois que essas ações forem executadas.

Conectar a PassKit à Braze

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

1. Em Settings, em Integrations no seu projeto ou programa de passes da PassKit, clique em Connect na guia Braze.
   
   
   
2. Informe sua chave de API da Braze, a URL do endpoint e um nome para seu conector.
   
   
3. Ative Enable Integration e os eventos que você deseja que a Braze dispare ou personalize suas mensagens.
   

Criar passe usando um link do SmartPass

Na Braze, você pode configurar um link SmartPass para gerar uma URL exclusiva para que seus clientes instalem o passe no Android ou no iOS. Para fazer isso, você deve definir uma carga útil de dados SmartPass criptografada que possa ser chamada a partir de um bloco de conteúdo da Braze. Esse bloco de conteúdo pode ser reutilizado para futuros passes e cupons. O seguinte é usado durante sua integração:

• URL da PassKit: sua URL da PassKit é uma URL exclusiva para seu programa da PassKit.
  Cada programa tem uma URL exclusiva, e você pode encontrá-la na guia Distribution do seu programa ou projeto da PassKit (por exemplo, https://pub1.pskt.io/c/ww0jir).
  
  
• Segredo da PassKit: juntamente com a URL, você deve ter em mãos a chave da PassKit para esse programa.
  Isso pode ser encontrado na mesma página que a URL da PassKit.
  
  
• ID do programa (ou projeto): o ID do programa da PassKit é necessário para criar a URL do SmartPass.
  Você pode encontrá-lo na guia Settings do seu projeto ou programa.

Para saber mais sobre como criar links SmartPass criptografados, consulte este artigo da PassKit.

Etapa 1: defina sua carga útil de dados de passe

Primeiro, defina a carga útil do cupom ou do membro.

Há muitos componentes diferentes que podem ser incluídos em sua carga útil, mas aqui estão dois importantes a observar:

Para obter uma lista completa dos campos disponíveis, seus tipos e descrições úteis, consulte a documentação da 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é Templates > Content Blocks no dashboard da Braze.

Selecione Create Content Block para começar.

Em seguida, você deve definir a Content Block Liquid Tag. Depois que o bloco de conteúdo é salvo, essa Liquid tag pode ser referenciada ao redigir mensagens. Neste exemplo, atribuímos a Liquid tag como {{content_blocks.${passKit_SmartPass_url}}}.

Nesse bloco de conteúdo, não incluiremos diretamente a carga útil, mas faremos referência a ela 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: crie sua assinatura de criptografia usando um hash HMAC SHA1

Em seguida, você criará sua assinatura de criptografia usando um hash HMAC SHA1 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 hashing.

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

Em seguida, gere uma assinatura usando esse hash e seu Project Secret. Isso pode ser feito com a inclusão de um terceiro trecho de código:

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

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

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

Etapa 4: imprima a URL

Por fim, chame sua URL final para que ela imprima a URL do SmartPass em sua mensagem.

1
{{longURL}}

Neste ponto, você criou um bloco de conteúdo com a seguinte aparência:

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

Nesse exemplo, foram adicionados parâmetros UTM para rastrear a origem dessas instalações até a Braze e essa Campaign.

Etapa 5: juntando tudo

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

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

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

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

Como redigir o corpo da mensagem

Você deverá capturar essas duas variáveis no corpo da mensagem e, em seguida, chamar o 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 %}

Faça referência ao bloco de conteúdo que você acabou de criar

1
{{content_block.${passkit_SmartPass_url}}}

O corpo da sua mensagem deve ser semelhante a este:

A URL de saída de exemplo é:

A URL de saída será longa. Isso acontece porque ela contém todos os dados do passe e incorpora segurança de ponta para garantir a integridade dos dados e impedir adulterações por meio de modificação de URL. Se estiver usando SMS para distribuir essa URL, talvez você queira executá-la por meio de um processo de encurtamento de links, como o bit.ly. Isso pode ser feito por meio de uma chamada de Conteúdo conectado para um endpoint do bit.ly.

Atualizar o passe usando o webhook da 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 usuário. Confira os links a seguir para obter informações sobre endpoints úteis da PassKit.

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

Parâmetros da carga útil

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

Etapa 1: crie seu modelo de webhook da Braze

Para criar um modelo de webhook da PassKit para usar em futuras Campaigns ou Canvas, navegue até a seção Modelos e mídia no dashboard da Braze. Se quiser criar uma campanha única de webhook da PassKit ou usar um modelo existente, selecione Webhook na Braze ao criar uma nova Campaign.

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

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

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

A PassKit requer um HTTP Header para autorização que inclui sua chave de API da 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 da PassKit. Para recuperar seu token, navegue até seu projeto/programa da PassKit, navegue até 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 seu caso de uso:

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

Etapa 2: pré-visualize sua solicitação

Seu texto bruto será automaticamente destacado se for uma tag Braze aplicável.

Pré-visualize a solicitação no painel Preview ou navegue até a guia Test, onde é possível selecionar um usuário aleatório, um usuário existente ou personalizar o seu próprio para testar o webhook.

Recuperar detalhes do passe pelo Conteúdo conectado

Além de criar e atualizar passes, também é possível recuperar os metadados dos passes dos usuários por meio do Conteúdo conectado da Braze para incorporar detalhes personalizados dos passes em suas campanhas de mensagens.

Chamada de Conteúdo conectado da 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 do 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