Oportunidades de valor agregado

Contexto

Agora é possível atualizar objetos e classes para incluir módulos de oportunidade de valor agregado. Os módulos vão aparecer na página de detalhes e podem ser vinculados ao conteúdo do emissor. Este documento descreve as etapas principais necessárias para ativar e usar módulos com a API Google Wallet.

Exemplo de recurso

Exemplo único do módulo de oportunidade de valor Exemplo de lista do módulo de oportunidade de valor
Visualização única Visualização de lista

O guia a seguir pressupõe que você conheça os conceitos básicos da Carteira do Google e já tenha concluído os pré-requisitos recomendados. Envie dúvidas ou feedback para seu ponto de contato da Carteira do Google.

Etapas de integração

Para adicionar um novo módulo, atualize o objeto e/ou a classe para incluir ValueAddedModuleData. ValueAddedModuleData tem os seguintes campos:

[Obrigatório] Cabeçalho LocalizedString

O cabeçalho exibido no módulo. O limite de caracteres é 60, e strings mais longas serão truncadas. Exemplo de cabeçalho de oportunidade de valor

Corpo de LocalizedString

O corpo exibido no módulo. O limite de caracteres é 50, e strings mais longas serão truncadas.
Exemplo de corpo de oportunidade de valor

Imagem de imagem

A imagem exibida no módulo. A proporção de imagem recomendada é 1:1, e as imagens serão redimensionadas para se ajustar a essa proporção.
Exemplo de imagem de oportunidade de valor

[Obrigatório] string uri

O URI para o qual o módulo direciona quando clicado. Pode ser um link da Web ou um link direto.

ModuleViewConstraints viewConstraints

Restrições que precisam ser atendidas para que o módulo seja mostrado. ModuleViewConstraints tem o seguinte campo:

TimeInterval displayInterval

O período em que o módulo será exibido aos usuários. É possível definir um `startTime` e um `endTime`. O módulo é exibido imediatamente após a inserção, a menos que um `startTime` seja definido. O módulo é exibido indefinidamente se `endTime` não estiver definido.

int32 sortIndex

O índice para classificar os módulos. Os módulos com um índice de classificação menor são mostrados antes dos módulos com um índice maior. Se não especificado, o índice de classificação será INT_MAX. Para dois módulos com o mesmo índice, o comportamento da classificação é indefinido.

Exemplo de ValueAddedModuleData:

  {
    "valueAddedModuleData": [
      {
        "header": {
          "defaultValue": {
            "language": "en-US",
            "value": "10% off merch"
          }
        },
        "body": {
          "defaultValue": {
            "language": "en-US",
            "value": "Shirts, caps, mugs, and more"
          }
        },
        "image": {
          "sourceUri": {
            "uri": "http://www.images.google.com/opportunity"
          }
        },
        "uri": "http://www.google.com/opportunity",
        "viewConstraints": {
          "displayInterval": {
            "start": {
              "date": "2024-08-01T18:30:00"
            },
            "end": {
              "date": "2025-08-01T18:30:00"
            }
          }
        },
        "sortIndex": 0
      },
      {
        "header": {
          "defaultValue": {
            "language": "en-US",
            "value": "10% off concessions"
          }
        },
        "uri": "http://www.google.com/new_opportunity"
      }
    ]
  }

Comportamento esperado

Depois de atualizar o objeto e/ou a classe, você vai encontrar módulos no passe correspondente. Se você adicionou apenas um módulo, ele vai aparecer na frente do cartão.

Diretrizes sobre módulos de oportunidade de valor agregado

Os módulos são oportunidades para você aumentar a experiência de passe do usuário com ações adicionais. Considere o seguinte ao criar e gerenciar os módulos:

  • Os módulos precisam ser definidos com a linguagem adequada para indicar que são acionáveis e ajudar os usuários a entender que eles podem ser clicados.
  • Os módulos precisam ter as imagens adequadas definidas e relacionadas a eles.
  • Você controla os módulos e precisa gerenciar proativamente a priorização deles, dependendo da importância e da relevância.
  • Mostre apenas os módulos ativos aos usuários. Para controlar isso, defina o displayInterval no módulo ou adicione ou remova proativamente da classe ou do objeto.

Como processar exceções

Mensagem Motivo
ValueAddedModuleData precisa conter um cabeçalho. ValueAddedModuleData não tem um cabeçalho.
"ValueAddedModuleData" precisa conter um URI preenchido. ValueAddedModuleData não tem um URI preenchido.
É permitido um máximo de 15 módulos de valor agregado por turma. É necessário reduzir os módulos de valor agregado na classe.
É permitido um máximo de 15 módulos de valor agregado por objeto. É necessário reduzir os módulos de valor agregado no objeto.