Ir para o conteúdo

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 aumentar e medir o engajamento das suas campanhas on-line ao entregar 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 físicas. Para isso, basta disparar mensagens baseadas em local e atualizações dinâmicas e personalizadas na carteira móvel do seu cliente.

Pré-requisitos

Requisito Descrição
Conta PassKit Você precisa ter uma conta PassKit e um gerente de conta PassKit.
userDefinedID Para atualizar corretamente os eventos personalizados e os atributos personalizados dos seus usuários entre a PassKit e a Braze, você precisa definir o ID externo da Braze como o userDefinedID. Esse userDefinedID é usado nas chamadas de API para os endpoints da PassKit.
Chave da API REST da Braze Uma chave da API REST da Braze com permissões users.track.

Você pode criá-la no dashboard da Braze em Configurações > Chaves de API.
Endpoint REST da Braze O URL do seu endpoint REST. Seu endpoint depende do URL da Braze para sua instância.

Integração

Para enriquecer ainda mais as experiências de carteira móvel de seus clientes, você pode enviar dados para a Braze pelo dashboard da PassKit. Para isso, use o endpoint /users/track da Braze.

Exemplos de dados para compartilhar a partir da PassKit:

  • Passe criado: quando um cliente clica em um link de passe e vê 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 forem enviados para a Braze, você pode criar públicos, personalizar conteúdo com Liquid e disparar Campaigns ou Canvas depois que essas ações forem realizadas.

Conectar a Passkit à Braze

Para enviar dados da PassKit, defina seu ID externo da Braze como o externalId da PassKit.

  1. Em Configurações, na seção Integrações do seu projeto ou programa de passes da PassKit, clique em Conectar na guia Braze.
    O bloco de integração da Braze na plataforma PassKit.

  2. Informe sua chave de API da Braze e a URL do endpoint. Depois, dê um nome ao seu conector.

  3. Ative Ativar integração e os eventos que você quer usar na Braze para disparar ou personalizar suas mensagens.
    O bloco de integração da Braze na PassKit expandido, com campos para a chave de API, URL do endpoint, nome da integração, configurações de ativação, configurações de associação e configurações de passes.

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

  • URL do PassKit: O URL do PassKit é um URL exclusivo do seu programa PassKit.
    Cada programa tem um URL exclusivo, que você encontra na guia Distribution do seu programa ou projeto PassKit (por exemplo, https://pub1.pskt.io/c/ww0jir).

  • Segredo do PassKit: Além do URL, você precisa ter em mãos a chave do PassKit desse programa.
    Ela fica na mesma página do URL do PassKit.

  • ID do programa (ou projeto): O ID do programa PassKit é necessário para criar o URL SmartPass.
    Você encontra esse ID na guia Settings do seu projeto ou programa.

Para saber mais sobre como criar links SmartPass criptografados, consulte Links SmartPass do PassKit no site do PassKit.

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

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

Há muitos componentes diferentes que você pode incluir na carga útil, mas aqui estão dois importantes:

Componente Obrigatório Tipo Descrição
person.externalId Obrigatório String Definido como o ID externo da Braze, é essencial para que os retornos de chamada do PassKit para a Braze funcionem, permitindo que os usuários da empresa tenham cupons para várias ofertas em uma única Campaign. Não precisa ser exclusivo.
members.member.externalId Opcional String Definido como o ID externo da Braze, você pode usar seu ID externo para atualizar o passe de associação. Definir esse campo exige que o usuário seja exclusivo dentro do programa de associação.

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

Exemplo de carga útil

{
  "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: Crie e codifique uma variável de carga útil indefinida

Crie e dê um nome a um novo Content Block acessando Content > Content Block no dashboard da Braze.

Selecione Create Content Block para começar.

Em seguida, defina a Content Block Liquid Tag. Depois que você salvar esse Content Block, essa Liquid tag poderá ser referenciada ao compor mensagens. Neste exemplo, atribuímos a Liquid tag como {{content_blocks.${passKit_SmartPass_url}}}.

Nesse Content Block, não vamos incluir a carga útil diretamente, mas sim referenciá-la em uma variável {{passData}}. O primeiro snippet de código que você precisa adicionar ao Content Block captura uma codificação Base64 da variável {{passData}}.

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

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

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

O segundo snippet de código que você precisa adicionar ao Content Block captura o URL que será usado no hash.

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

Depois, gere uma assinatura usando esse hash e o seu Project Secret. Para isso, inclua um terceiro snippet de código:

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

Por fim, anexe a assinatura ao URL completo usando o quinto snippet de código:

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

Etapa 4: Imprima seu URL

Por último, chame o URL final para que ele imprima o URL SmartPass na sua mensagem.

{{longURL}}

Neste ponto, você criou um Content Block parecido com este:

{% 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, foram adicionados parâmetros UTM para rastrear a origem dessas instalações até a Braze e esta Campaign.

Etapa 5: Juntando tudo

Depois de criado, esse Content Block pode ser reutilizado no futuro.

Você deve ter notado que há duas variáveis não definidas no exemplo de Content Block.
{{passData}} - A carga útil de dados do passe em JSON definida na etapa 1
{{projectUrl}} - O URL do seu projeto ou programa, que você encontra na guia de distribuição do seu projeto Passkit.

Essa escolha é intencional e favorece a reutilização do Content Block. Como essas variáveis são apenas referenciadas, e não criadas dentro do Content Block, elas podem mudar sem que seja preciso refazer o Content Block.

Por exemplo, talvez você queira mudar a oferta de boas-vindas para incluir mais pontos iniciais no seu programa de fidelidade, ou criar um segundo cartão de membro ou cupom. Esses cenários exigiriam projectURLs diferentes do Passkit ou cargas úteis de passe diferentes, que você definiria por Campaign na Braze.

Compondo o corpo da mensagem

Capture essas duas variáveis no corpo da mensagem e depois chame o seu Content Block. Capture a carga útil JSON minificada da etapa 1:

Atribua o URL do projeto

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

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

Referencie o Content Block que você acabou de criar

{{content_block.${passkit_SmartPass_url}}}

O corpo da sua mensagem deve ficar parecido com este: Criador de mensagem com o JSON capturado e a referência ao Content Block.

O URL de saída do exemplo é: URL de saída com uma longa sequência de letras e números gerada aleatoriamente.

O URL de saída será longo. Isso acontece porque ele contém todos os dados do passe e incorpora segurança de alto nível para garantir a integridade dos dados e evitar adulterações por meio de modificação do URL. Se você usar SMS para distribuir esse URL, talvez seja interessante passá-lo por um processo de encurtamento de links, como o bit.ly. Isso pode ser feito com uma chamada de Connected Content para um endpoint do bit.ly.

Atualizar 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 seu usuário. Confira os links a seguir para saber mais sobre endpoints úteis da PassKit.

Parâmetros da carga útil

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

Dados Tipo Descrição
externalId String Permite adicionar um ID exclusivo ao registro do passe para oferecer compatibilidade com um sistema existente que usa identificadores exclusivos de clientes (por exemplo, números de associação). Você pode recuperar os dados do passe usando este endpoint via userDefinedId e campaignName em vez do ID do passe. Esse valor deve ser exclusivo dentro de uma campanha e, depois de definido, não pode ser alterado.

Para a integração com a Braze, recomendamos usar o ID externo da Braze: {{${user_id}}}
campaignId (cupom)

programId (associação)
String O ID da campanha ou do modelo de programa que você criou na PassKit. Para encontrá-lo, acesse a guia Configurações no seu projeto de passe da PassKit.
expiryDate Data e hora IO8601 A data de vencimento do passe. Após a data de vencimento, o passe é anulado automaticamente (consulte isVoided). Esse valor substituirá o valor da data de término do modelo e da campanha.
status String O status atual de um cupom, como REDEEMED ou UNREDEEMED.

Etapa 1: Crie seu modelo de webhook da Braze

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

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 e método da solicitação

A PassKit exige um HTTP Header para autorização que inclua sua chave de API da PassKit codificada em base 64. Os itens a seguir já estarão incluídos no modelo como um par chave-valor, mas, na guia Configurações, você deve substituir o <PASSKIT_LONG_LIVED_TOKEN> pelo seu token da PassKit. Para recuperar seu token, acesse seu projeto/programa da PassKit e depois vá em 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 da carga útil necessários para o seu caso de uso:

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

Etapa 2: Faça uma prévia da sua solicitação

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

Faça uma prévia da sua solicitação no painel Prévia ou acesse a guia Teste, onde você pode selecionar um usuário aleatório, um usuário existente ou personalizar o seu próprio para testar o 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 do passe às suas campanhas de mensagens.

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

Exemplos de respostas do Liquid

{
    "redemptionDate": null,
    "redemptionCode": "",
    "lat": 0,
    "lon": 0,
    "alt": 0,
    "redemptionSource": "",
    "redemptionReference": "",
    "transactionReference": "",
    "transactionAmount": 0
}
UNREDEEMED
New Stuff!