Criar Campanhas de Passes da Carteira

Uma Campanha de Passes da Carteira permite que você crie um único modelo de passe da Apple Wallet ou Google Wallet, emita-o para vários usuários e gerencie as atualizações de forma centralizada.

Você escolhe quais campos são Compartilhados (sincronizando alterações para todos os dispositivos dos usuários simultaneamente) e quais são Pessoais (preservando valores únicos como nomes, códigos de barras ou saldos para cada usuário).

Nota

Uma Campanha de Passes da Carteira não está relacionada a uma campanha de Customer Journey ou a uma notificação push. É uma ferramenta para gerenciar modelos de passes, emissão e atualizações de passes em tempo real.

O que você pode fazer com as Campanhas de Passes da Carteira

• Criar um passe em uma campanha, em vez de configurar cada passe manualmente no construtor de passes da Apple Wallet ou Google Wallet.
• Escolher quais campos são atualizados em todos os lugares (compartilhados) e quais permanecem por passe (pessoais).
• Ver quantos passes emitidos uma edição de campo afeta antes de salvá-la.
• Substituir um campo compartilhado em um passe e, posteriormente, devolver o controle à campanha.
• Anexar passes emitidos fora de uma campanha para que comecem a seguir seus campos compartilhados.
• Acompanhar as revisões da campanha e o status de entrega de cada atualização.
• Atualizar automaticamente um passe sempre que a tag por trás de um de seus campos mudar, sem editar a campanha.

Pré-requisitos

Uma campanha usa a mesma configuração única de um passe avulso:

Apple Wallet:

• Assinatura ativa do Apple Developer Program
• Plataforma iOS conectada ao aplicativo
• Certificado de assinatura de passe carregado no Pushwoosh

Google Wallet:

• Conta de emissor ativa no Google Pay & Wallet Console
• Google Wallet configurado para o aplicativo (ID do Emissor e chave de conta de serviço do Google Cloud)

Criar uma campanha

Para começar a criar uma campanha, vá para Campanhas → Passes da Carteira → Campanhas e clique em Criar campanha.

Definir detalhes e plataforma da campanha

• Plataforma: selecione Apple Wallet ou Google Wallet no topo da página. Esta escolha é permanente para a campanha.
• Campanha: insira um Nome e uma Descrição opcional para sua referência interna. Nenhum dos dois aparece no passe.
• Formato do passe: em Estilo do Passe (Apple) ou Tipo de Passe (Google), escolha o layout para o seu passe:
  • Apple Wallet: Cartão de Embarque, Cupom, Ingresso para Evento, Cartão de Loja, Genérico. Veja Escolha um estilo de passe.
  • Google Wallet: Genérico, Oferta, Cartão de Fidelidade, Ingresso para evento, Cartão-presente, Voo, Transporte. Isso não pode ser alterado após a criação. Veja Escolha um tipo de passe.

Configurar o design e a marca do passe

Configure as seções padrão do passe:

• Informações Básicas, Cores e Código de Barras: defina o título do passe, as cores de fundo e do texto e o tipo de código de barras. Para orientações detalhadas sobre cada seção, consulte Criar passes no construtor de passes da Apple Wallet ou Criar passes do Google Wallet no construtor de passes.
• Campos do passe: adicione os campos que devem aparecer no cartão (veja campos do passe da Apple Wallet ou campos e detalhes do Google Wallet).
• Expiração: defina datas relevantes e regras de expiração (veja expiração da Apple Wallet ou expiração do Google Wallet).
• Localizações: defina a relevância baseada na localização (veja localizações da Apple Wallet ou localizações do Google Wallet).

Dica

Para o Google Wallet, use Quem pode salvar o passe para controlar se o passe está vinculado a uma única conta do Google, a um único dispositivo ou acessível a qualquer pessoa com o link.

Definir campos compartilhados e pessoais

Na seção Campos compartilhados e pessoais, configure quais campos são atualizados globalmente em todos os passes e quais mantêm valores únicos por usuário. Isso controla o que acontece quando você edita a campanha posteriormente: os campos compartilhados são atualizados em todos os passes emitidos, enquanto os campos pessoais permanecem inalterados.

Ative o seletor Pessoal para qualquer campo que deva conter valores únicos por usuário.

Tipo de campo	Comportamento	Exemplos
Compartilhado	Controlado pela campanha. A atualização deste campo sincroniza o novo valor para cada passe nos dispositivos dos usuários.	Data do evento, Número do portão, Endereço da loja, Percentual de desconto
Pessoal	Único por usuário. A campanha não substitui esses valores quando atualizada.	Nome do usuário, Número do assento, ID de membro, Saldo de pontos

O valor de um campo pessoal pode incluir um placeholder de tag, {tag} ou {tag|format|fallback} (por exemplo, {Seat}). O Pushwoosh o preenche a partir da tag do destinatário quando serve o passe. Se o destinatário não tiver valor para essa tag, o Pushwoosh usa o fallback do placeholder ou deixa o campo em branco quando o placeholder não tem nenhum.

• Apenas a tag, nada mais, como {Seat}: o campo não aparece na caixa de diálogo Emitir passe.
• A tag misturada com outro texto, como Assento {Seat}, ou nenhuma tag: o campo aparece como uma entrada editável na caixa de diálogo Emitir passe, pré-preenchido com esse valor. Qualquer tag dentro dele ainda é resolvida por destinatário quando o Pushwoosh serve o passe.

Dica

O código de barras de um passe é configurado e personalizado na seção Código de Barras. Veja código de barras da Apple Wallet ou código de barras do Google Wallet para detalhes.

Ativar a sincronização de tags

Na seção Sincronização de tags, ative Atualizar campos do passe a partir de tags para que o Pushwoosh verifique periodicamente os placeholders de tags usados nos campos da campanha e envie um novo valor para qualquer passe cuja tag tenha mudado.

• Intervalo (minutos): com que frequência o Pushwoosh relê as tags. O padrão é 60 e não pode ser inferior a 5. Um passe recebe no máximo uma atualização por intervalo, não importa quantas vezes sua tag mude nesse meio tempo.
• Notificação (apenas Google Wallet): escolha como o portador fica sabendo da atualização: Silenciosamente, Mensagem própria (preencha o Texto da mensagem, enviado com a atualização) ou Notificação de campo do Google (o próprio alerta de atualização de campo do Google). O Google os limita a 3 por passe a cada 24 horas. Passado esse limite, os novos valores ainda chegam ao passe, mas sem notificação.

Nota

A Apple Wallet não tem uma notificação para toda a campanha, então este seletor não aparece para campanhas da Apple. O texto da notificação reside no próprio campo. Preencha a Mensagem de alteração em cada campo no construtor de passes da Apple Wallet.

Cuidado

A sincronização de tags só é executada enquanto o status da campanha for Ativo. Defina-o como Rascunho ou Arquivado para pausar as verificações agendadas sem desativar o seletor.

Ativar a sincronização de tags para uma campanha que já possui passes emitidos não espera o primeiro intervalo. A próxima verificação agendada trata uma campanha que nunca sincronizou como devida imediatamente, e no modo Mensagem própria ou Notificação de campo do Google, isso pode notificar todos os portadores de uma vez e gastar o limite de 3 por 24 horas do passe em uma única execução.

Carregar imagens da campanha

1. Na seção Imagens da campanha, clique em Escolher uma imagem ao lado de um espaço de imagem.
2. Selecione uma imagem existente do seu Armazenamento de mídia ou arraste e solte um novo arquivo para carregar.
3. Repita para cada espaço de imagem disponível:
   • Apple Wallet: Ícone, Logotipo, Fundo, Rodapé, Faixa e Miniatura (veja imagens da Apple Wallet).
   • Google Wallet: Logotipo e Imagem principal.

Nota

• As imagens devem ter menos de 10 MB e 25 megapixels.
• Apple Wallet: ao contrário de um passe avulso, onde as imagens são bloqueadas após a criação, uma atualização de imagem da campanha atinge todos os passes emitidos.
• Google Wallet: um passe avulso já permite que você altere seu logotipo e imagem principal a qualquer momento via Editar. Uma imagem de campanha funciona da mesma forma, exceto que uma edição atinge todos os passes emitidos de uma vez, em vez de apenas um.

Visualizar e criar a campanha

1. Verifique o painel Visualizar como usuário à direita para ver a aparência do cartão. Você pode inserir um ID de Usuário de teste para visualizar campos personalizados.

Dica

Clique em Validar passe para verificar o design em relação aos requisitos da Apple ou do Google antes de salvar, sem criar a campanha ainda.

2. Clique em Criar campanha na parte inferior da página.

O Pushwoosh cria a campanha com o status Rascunho e abre seu espaço de trabalho, com as abas Design, Passes e Histórico.

Nota

A criação de uma campanha apenas salva o design do passe e não envia passes aos usuários. Para distribuir passes ao seu público, prossiga para Emitir passes para os usuários.

Emitir passes para os usuários

Emitir um passe da campanha

1. Na aba Passes, clique em Emitir passe.
2. Insira o ID do Usuário Pushwoosh do destinatário.

3. Clique em Emitir passe para confirmar.

Dependendo de como você configurou os Campos pessoais, o modal os trata da seguinte forma:

• Campos editáveis: aparecem com valores padrão que você pode alterar para este usuário.
• Placeholders de tags (como {Seat}): não aparecem na caixa de diálogo. O Pushwoosh os preenche automaticamente a partir das tags do usuário.

Você também pode editar qualquer campo pessoal em um passe individual a qualquer momento após a emissão.

O Pushwoosh gera o passe a partir do design atual da campanha e o lista na aba Passes e na tabela Todos os passes do aplicativo (Apple Wallet ou Google Wallet).

Entregue o passe ao destinatário

A emissão de um passe cria o registro do passe no Pushwoosh. Para entregá-lo ao dispositivo do usuário, compartilhe o link de instalação:

1. Abra o menu de ações do passe na aba Passes ou em Todos os passes.
2. Selecione Copiar link de instalação ou Código QR. Os passes da Apple Wallet também oferecem Baixar para o arquivo .pkpass assinado.
3. Envie o link ou arquivo para o destinatário via push, e-mail, SMS ou uma Customer Journey. Para emitir um passe e entregar seu link automaticamente à medida que os viajantes avançam em uma jornada, use o elemento Emitir Passe da Carteira em vez de emiti-lo aqui.

Para mais maneiras de distribuir passes, veja Compartilhar passes da Apple Wallet ou Compartilhar passes do Google Wallet.

Anexar um passe existente a uma campanha

Você pode anexar passes avulsos (criados fora de qualquer campanha) a uma campanha para que eles comecem a receber atualizações compartilhadas.

1. Na aba Passes, clique em Anexar passes.
2. Procure por passes por ID do Usuário, número de série ou código de barras.
3. Selecione os passes e confirme.

Uma vez anexado:

• Os campos compartilhados começam a seguir a campanha e são atualizados sempre que você altera o modelo do passe.
• Os valores pessoais já existentes no passe (como detalhes do usuário ou saldos únicos) são preservados.

Anexar passes via API

Você também pode anexar passes programaticamente usando o método da API AttachPasses (até 500 números de série por solicitação).

Se um passe não puder ser anexado, a API retorna o motivo específico para aquele serial:

• O passe já está atribuído a outra campanha.
• O estilo do passe não corresponde ao formato da campanha.
• O passe não possui campos de campanha obrigatórios.
• O número de série não existe ou pertence a uma plataforma diferente.

Gerenciar uma campanha existente

Abrir uma campanha criada em Campanhas → Passes da Carteira → Campanhas exibe seu status, contador de revisões, visualização do passe ao vivo e três abas principais: Design, Passes e Histórico.

Alterar o status da campanha

Use o status para acompanhar em que ponto cada campanha está: ainda sendo projetada, emitindo passes ativamente, ou concluída e arquivada.

Para alterar o status, selecione uma opção no menu suspenso Status no cabeçalho da campanha. A alteração é salva imediatamente sem uma etapa de confirmação separada:

• Rascunho ou Ativo: permite que você emita novos passes, anexe passes existentes e envie atualizações de design.
• Arquivado: pausa a emissão de novos passes. Você não pode emitir ou anexar passes enquanto a campanha estiver arquivada, mas os passes emitidos anteriormente continuam funcionando e recebendo atualizações compartilhadas.

Aba Design

Na aba Design, você pode atualizar o modelo do passe, alterar cores, modificar campos compartilhados e pessoais, carregar novas imagens da campanha ou alterar as configurações de sincronização de tags.

Atualizar o design e enviar alterações para os passes

1. Na aba Design, edite informações básicas, cores, tipo de código de barras, expiração, localizações, um campo compartilhado ou uma imagem da campanha.
2. Clique em Salvar alterações.
3. Na caixa de diálogo Aplicar a edição da campanha, confirme a atualização:
   • Nenhum passe substitui o campo alterado: clique em Atualizar N, manter edições manuais para enviar a edição para todos os N passes.
   • Alguns passes substituem o campo alterado: a caixa de diálogo nomeia o campo e quantos passes o substituem. Clique em Atualizar N, manter edições manuais para enviar a edição para todos os passes, exceto esses, ou Sobrescrever todos os N para enviá-la a todos os N passes, incluindo os substituídos. A substituição apaga a substituição.

Qualquer que seja o botão que você clicar, a atualização é salva como uma nova revisão (por exemplo, Revisão 2), para que você possa verificar o que mudou e quando na aba Histórico.

Nota

Uma edição feita quando nenhum passe foi emitido ainda é salva imediatamente sem uma caixa de diálogo de confirmação, porque não há passes existentes para atualizar.

Substituir um campo compartilhado em um passe individual

Se você precisar personalizar um campo compartilhado para um usuário específico, edite esse campo diretamente em seu passe individual (a partir da aba Passes ou Todos os passes):

• Criar uma substituição: salvar um valor personalizado em um passe individual desvincula esse campo das atualizações de toda a campanha. Atualizações futuras na campanha, incluindo uma atualização agendada de sincronização de tags, pularão este passe para esse campo específico.
• Remover uma substituição: para restaurar o controle da campanha, edite o passe e clique em Usar o valor da campanha ao lado do campo substituído.

Você pode acompanhar quais passes têm valores personalizados na aba Passes na coluna Campos fixados.

Aba Passes

A aba Passes lista todos os passes emitidos pela campanha, incluindo seu número de série, ID do Usuário do destinatário, campos fixados ativos, revisão atual e data da última atualização.

Se a sincronização de tags estiver ativada, a aba também mostra uma linha Tags sincronizadas acima da tabela com a data e hora da última execução agendada, ou ainda não antes da primeira.

Use os filtros da tabela para encontrar passes específicos:

• Com campos fixados: mostra os passes que têm pelo menos um campo editado de forma personalizada.
• Atrás da revisão: mostra os passes que ainda não receberam a última atualização da campanha.

Para emitir novos passes ou anexar passes existentes, veja Emitir passes para os usuários.

Abra o menu de ações de uma linha (⋮) para gerenciar esse passe:

• Editar: abra o passe na página de edição de sua plataforma para alterar campos pessoais ou substituir um campo compartilhado.
• Baixar: em campanhas da Apple Wallet, baixe o arquivo .pkpass assinado. Campanhas do Google Wallet não mostram esta opção, pois o Google Wallet não tem um arquivo para download equivalente.
• Enviar mensagem: abra o compositor de push único para enviar uma mensagem ao destinatário do passe por ID do Usuário. Veja Enviar mensagem aos portadores de passes da Carteira para todas as maneiras de alcançá-los.
• Código QR: mostre um código QR de instalação que os usuários podem escanear para adicionar o passe e registrar seu dispositivo para atualizações.
• Copiar link de instalação: copie a URL de instalação para compartilhar o passe em seus canais de mensagens.
• Excluir: remova o passe. Isso não pode ser desfeito. Na Apple Wallet, as cópias já instaladas param de receber atualizações e se tornam inválidas na próxima atualização. No Google Wallet, o Google não permite a remoção forçada de um passe já salvo em um dispositivo, então ele se torna inválido e é movido para os Passes expirados do usuário, enquanto o Pushwoosh remove seu registro. Excluir um passe aqui não exclui a campanha ou qualquer outro passe emitido.

Aba Histórico

A aba Histórico lista todas as revisões da campanha em ordem cronológica, mostrando quais campos foram modificados em cada versão.

O status de entrega da atualização mais recente aparece abaixo das abas:

• Cancelar: para de enviar a atualização para os passes que ainda não a receberam. Esses passes permanecem em sua revisão anterior.
• Tentar novamente falhas: tenta novamente a entrega para os passes que falharam na atualização (marcados como falha após 5 tentativas).

Uma vez que uma nova revisão é salva, as atualizações mais antigas não podem mais ser tentadas novamente ou canceladas.

Excluir uma campanha

Abra a campanha e clique em Excluir campanha no canto superior direito da página.

A exclusão de uma campanha não exclui ou invalida os passes já emitidos. Os passes emitidos mantêm seu conteúdo e imagens atuais, mas param de receber atualizações compartilhadas. Quaisquer alterações futuras devem ser feitas em cada passe individualmente.