Acionar notificações push

Notificações acionadas por parceiros

Adicionar mensagem e notificar

Contexto

Depois que um usuário adicionar um cartão, talvez você queira enviar uma mensagem relacionada a ele e garantir que ele seja notificado sobre isso. Ao usar a solicitação da API Add Message com um message_type igual a TEXT_AND_NOTIFY, o seguinte acontece:

  1. Um item Mensagem é adicionado ao "verso do cartão" (também conhecido como Modelo de detalhes), e uma notificação push é enviada aos usuários com o cartão salvo.
  2. Quando o usuário toca na notificação, a Carteira do Google é aberta na frente do cartão (também conhecido como visualização de cartão), e uma caixa de texto aparece na parte de cima da tela com um botão "Ver mensagem".
  3. Ao clicar no destaque, os usuários acessam a parte de trás do cartão, onde as novas mensagens não lidas são destacadas.

Algumas considerações ao enviar mensagens com notificações para os usuários

  • Os usuários precisam ativar as notificações para receber as notificações push relacionadas a mensagens.
  • As mensagens podem conter URIs para seu site ou app. Os hiperlinks precisam ser de um site ou app relacionado ao cartão. É uma violação da Política de uso aceitável enviar usuários para links não relacionados ao cartão.
  • É possível enviar no máximo três mensagens que acionam uma notificação push em um período de 24 horas. O Google pode reduzir sua cota de entrega de notificações push se considerar que você está enviando spam para seus usuários.
  • A notificação push que os usuários veem na tela de bloqueio é controlada pela Carteira do Google.
  • É possível usar os métodos UPDATE ou PATCH para editar ou remover dados de mensagens usando o endpoint regular de classe ou objeto.

Etapas de integração

Quando você quiser notificar os usuários sobre uma nova mensagem do emissor adicionada usando a API AddMessage, será necessário atualizar o AddMessageRequest para que a Message que contém o novo texto tenha o MessageType TEXT_AND_NOTIFY em vez de TEXT.

Exemplo de solicitação JSON para adicionar uma mensagem e notificar em uma classe de passes

  …
  "id": ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Class message header",
        "body": "My Class message body with a <a href="https://wallet.google">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

Exemplo de solicitação JSON para adicionar uma mensagem e notificar em um objeto de cartão

  …
  "id": OBJECT_ID",
  "classId": "ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Object message header",
        "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

Exemplo de Response para adicionar uma mensagem e notificar sobre uma classe de cartão

  // The updated resource
  …
    {
      "kind": "walletobjects#walletObjectMessage",
      "header": "My Object message header",
      "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
      "id": "message_id",
      "messageType": "textAndNotify"
    },
  …

Como processar exceções

Qualquer tentativa de notificar mais de três vezes vai gerar uma resposta QuotaExceededException . Outras atualizações do cartão podem ser definidas usando "TEXT" em vez de "TEXT_AND_NOTIFY", conforme discutido nas Etapas de integração.

Atualizar campo e notificar

Contexto

Depois que um usuário adiciona um cartão, talvez você queira acionar uma notificação push ao atualizar determinados campos. A notificação vai aparecer na tela de bloqueio do usuário e informar que há uma atualização no cartão. Essa notificação só será acionada para um subconjunto específico de campos definidos abaixo usando os métodos de API UPDATE e PATCH. Quando uma chamada de API para atualizar o cartão é feita, o seguinte acontece:

  1. Uma notificação push é acionada e exibida na tela de bloqueio do usuário, informando sobre uma atualização do cartão.
  2. Quando o usuário toca na notificação, a Carteira do Google é aberta na frente do cartão (também conhecido como visualização de cartão), e uma caixa de texto aparece na parte de cima da tela com um botão "Analisar atualização".
  3. Ao clicar no botão, o usuário acessa uma tela em que pode ver os campos que foram alterados pela atualização.

Algumas considerações ao enviar notificações de atualização de campo

  • Os usuários precisam ativar as notificações para receber as notificações push relacionadas a atualizações.
  • É possível enviar no máximo três atualizações que acionam uma notificação push em um período de 24 horas. O Google pode reduzir sua cota de entrega de notificações push se considerar que você está enviando spam para seus usuários.
  • A notificação push que os usuários veem na tela de bloqueio é controlada pela Carteira do Google.
  • O campo notifyPreference é transitório e existe apenas nesta solicitação. Para solicitações futuras em que você quiser acionar uma notificação, será necessário redefinir esse campo na solicitação de classe ou objeto.

Etapas de integração

Para acionar essas notificações, use as chamadas UPDATE ou PATCH existentes e especifique o notifyPreference. Ao atualizar um campo em uma classe ou objeto, você pode adicionar um novo campo, notifyPreference, à solicitação de classe ou objeto para acionar a notificação.

Exemplo de solicitação JSON para atualizar e notificar em uma turma

    …
    "dateTime":
        {
            "kind": "walletobjects#eventDateTime",
            "doorsOpen": "2024-09-23T19:20:50.00"
        },
    "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
    "notifyPreference": "notifyOnUpdate",
    …

Definir o notifyPreference como notifyOnUpdate vai acionar uma notificação, desde que o campo atualizado seja compatível.

Campos aceitos

FlightObject
  • boardingAndSeatingInfo.seatNumber
  • boardingAndSeatingInfo.seatAssignment

Notificações próximas

Esse recurso mostra aos usuários que ativaram as notificações e concederam acesso preciso e constante à localização no app Google Carteira uma notificação push lembrando que eles salvaram um cartão relevante para a localização atual.

Etapas de integração

Como usar

Para usar esse recurso, adicione locais às suas classes e objetos. É possível adicionar até 10 locais por classe e 10 por objeto. Use MerchantLocations na definição de classe ou objeto. É possível adicionar esses locais ao usar os métodos insert, patch ou update.

Depois de adicionar locais a uma classe ou objeto, o Google envia notificações aos usuários quando eles estão por perto. O Google decide a proximidade e o tempo que um usuário precisa ficar na área para que a notificação seja enviada. O Google também controla o texto da notificação.

Exemplo de uma LoyaltyClass com o MerchantLocations definido: 
{
  "kind": "walletobjects#loyaltyClass",
  "programLogo": {
  "kind": "walletobjects#image",
  "sourceUri": {
    "uri":
    ...
  }
  },
  "localizedProgramName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Program Name",
    }
  },
  "id": Id1234,
  "version": "1",
  "allowMultipleUsersPerObject": true,
  "reviewStatus": "underReview",
  "enableSmartTap": false,
  "localizedIssuerName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Issuer Name"
    }
  },
  "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
  "merchantLocations": [
    {
      "latitude": 37.79020867928078,
      "longitude": -122.39004
    },
    {
      "latitude": 37.42587,
      "longitude": -122.08620
    },
  ]
}

Comportamento esperado

Os usuários vão receber notificações fixas sobre os cartões quando estiverem em um dos MerchantLocations especificados. Se a pessoa clicar na notificação, o cartão será aberto na Carteira do Google. Os usuários podem dispensar a notificação com o gesto de deslizar. Quando um usuário sair do local, a notificação vai desaparecer.

Notificações automáticas acionadas pela Carteira do Google

Próxima notificação

A Carteira do Google envia uma notificação ao usuário três horas antes do voo. O tempo de voo é definido por class.localScheduledDepartureDateTime.

Para receber essa notificação, o usuário precisa ter as notificações ativadas. Para verificar isso, ele pode navegar até Configurações > Notificações e ver se a opção Atualizações sobre seus cartões está ativada.

A mensagem será exibida na área de notificações e também na tela de bloqueio se o usuário tiver ativado notificações nessa tela.

A notificação tem o seguinte formato não modificável: 

  Boarding pass for your flight to class.destination.airportIataCode

Se ele tocar na notificação e desbloquear o dispositivo, o cartão será exibido no app Carteira do Google.

Se o usuário tiver vários cartões, somente será mostrado o próximo que poderá ser utilizado. Se os cartões agrupados tiverem sido salvos de acordo com as instruções em Agrupar vários cartões de embarque, a notificação mostrará apenas um dos cartões do grupo. No entanto, depois de tocar na notificação, o usuário pode ver os outros cartões nesse grupo ao deslizar para a esquerda ou direita.

A notificação é fixada e não será dispensada automaticamente depois que um usuário a abrir. Isso vai acontecer 60 minutos após class.localScheduledDepartureDateTime.

Notificação de atualização de voo

Quando determinados campos de um voo são alterados, os usuários com um ou mais cartões de embarque adicionados recebem uma notificação push no dispositivo. Isso acontece somente se condições específicas forem atendidas.

Terminal de origem e portão

Se você alterar class.origin.terminal ou class.origin.gate e a condição a seguir for atendida, uma notificação será enviada informando que o campo foi alterado.

  • Faltam menos de três horas para class.localScheduledDepartureDateTime.

A notificação é exibida no seguinte formato: "A companhia aérea X atualizou o portão para A1". Não é possível mudar o formato.

Horário de embarque e de partida

Se você alterar class.localBoardingDateTime ou class.localEstimatedOrActualDepartureDateTime, e as condições abaixo forem atendidas, uma notificação será enviada informando que o campo foi alterado.

  • Faltam menos de 24 horas para class.localScheduledDepartureDateTime.
  • O horário em questão é alterado em pelo menos 10 minutos.

A notificação é exibida no seguinte formato: "_A companhia aérea X atualizou o horário de embarque para 18h._" O formato ou idioma não pode ser personalizado.