Como emitir wallet passes personalizados via API

Uma API de wallet pass permite que o seu backend crie um passe para cada cliente, com o nome, o saldo, o código de barras e as localizações dele, e depois atualize esse passe sempre que os seus dados mudarem. Você cria o template uma vez, envia os valores pessoais por usuário e recebe de volta um link de instalação para o Apple Wallet ou um link de salvamento (save link) para o Google Wallet.

Nem todo time precisa disso. Os exemplos usam a API de Wallet passes do Pushwoosh, em que cada passe fica vinculado a um User ID que também move seus push, e-mails e jornadas. Para times de produto em FinTech, e-commerce e delivery no Brasil, é essa ligação que permite personalizar notificações push e passes em escala a partir dos mesmos dados.

Quando a API ganha do construtor

O construtor é a ferramenta certa para desenhar um passe e para envios pequenos ou pontuais. A API assume quando os passes dependem de dados que estão nos seus próprios sistemas.

Olhe a coluna da jornada antes de escrever qualquer linha de código. Se o gatilho é uma ação do cliente que o Pushwoosh já rastreia, a etapa Issue Wallet Pass (emitir wallet pass) no Customer Journey muitas vezes dispensa código próprio.

Templates e valores pessoais

O padrão é o mesmo nas 2 plataformas. Um template guarda o layout, a identidade visual e a estrutura dos campos. Os valores de cada usuário o preenchem no momento da emissão.

Valores pessoais são o que muda de 1 cliente para outro: nome, número de membro, pontos, nível, valor do código de barras, validade, loja mais próxima. Todo o resto vem do template, então uma mudança de design vale para todos os passes novos sem mexer na sua integração.

Numa jornada, a etapa Issue Wallet Pass recebe as campanhas de passe da Apple e do Google (apple_campaign_id, google_campaign_id) e os personal_values a preencher. 1 etapa pode emitir as 2 versões para o mesmo User ID.

O fluxo do Apple Wallet

Tudo o que o construtor de passes da Apple faz também está disponível na Apple Wallet PassKit API: criar, atualizar, listar, baixar e excluir passes.

Uma integração típica tem 4 etapas.

Você precisa de um certificado Pass Type ID (.p12) por aplicação e de uma conta Apple Developer (US$ 99 por ano). A configuração está na documentação de configuração de wallet pass no iOS.

O fluxo do Google Wallet

A Google Wallet API cobre o mesmo ciclo de vida para os passes do Google. Num mercado como o Brasil, dominado pelo Android, este costuma ser o fluxo que você integra primeiro.

Você precisa de um Issuer ID do Google Pay & Wallet Console, com a conta de serviço do Pushwoosh convidada para o seu emissor, configurado uma vez por aplicação. A configuração está na documentação de configuração do Google Wallet.

Atualizações em escala

É nas atualizações que a API se paga. Um extrato de pontos ou um sistema de reservas pode atualizar o passe no momento em que um valor muda, então o cartão na wallet do cliente bate com a sua fonte da verdade. Numa FinTech ou num e-commerce, a confirmação de um pagamento via PIX é um bom exemplo desse gatilho em tempo real.

3 regras deixam as grandes rodadas de atualização seguras:

• Parta do passe atual. A atualização da Apple recebe o objeto completo do passe, então busque o passe e mude só os valores que mudaram. A atualização do Google aplica um patch no objeto.
• Decida os alertas campo a campo. Na Apple, só campos com mensagem de alteração mostram alerta na tela de bloqueio. No Google, notifyOnUpdate pede ao Google o alerta próprio dele, que só dispara em passes de fidelidade, ingressos de eventos e cartões de embarque, no máximo 3 por passe em 24 horas. notifyMessage envia o seu próprio texto de notificação no Android em qualquer tipo de passe.
• Mantenha os alertas sobre o passe. A Apple e o Google permitem notificações sobre o passe, não promoções. As ofertas de Black Friday vão por push, e-mail ou SMS.

Exemplos de código

As 2 APIs usam a URL base https://apple-passkit.svc-nue.pushwoosh.com e o seu token de acesso à API do Pushwoosh no cabeçalho Authorization: Token <api-token>. Os corpos de requisição abaixo são os exemplos da referência da API.

Criar um passe do Apple Wallet: POST /api/pass/create. A resposta devolve o serialNumber do passe.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Criar um passe do Google Wallet: POST /api/google/pass/create. A resposta devolve o serialNumber e um saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Para atualizar, envie o novo conteúdo com o número de série: POST /api/pass/update/{serialNumber} para a Apple, POST /api/google/pass/update/{serialNumber} para o Google.

Construtor, API ou jornada: uma regra rápida

Use o construtor para desenhar e testar. Use a etapa da jornada quando o gatilho é um evento do cliente que já está no Pushwoosh, como um cadastro ou uma primeira compra. Use a API quando o gatilho ou os dados estão no seu backend.

A maioria dos times acaba usando os 3, e tudo bem: o construtor para o design, as jornadas para os momentos do ciclo de vida, a API para saldos e status em tempo real. O erro é forçar 1 deles a fazer o trabalho dos outros.

Personalize cada passe em escala com o Pushwoosh

O Pushwoosh oferece um construtor visual, uma etapa de jornada e uma API para passes nativos do Apple e do Google Wallet, sem um fornecedor de passes separado no meio. Cada passe compartilha o User ID com seus push, mensagens in-app, e-mails e SMS, então 1 conjunto de dados alimenta todos os canais.

Personalizar em escala não é questão de ter mais templates. É ter 1 fonte da verdade que todo cartão em toda wallet reflete.

FAQ