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 explica as principais etapas 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 de módulos de valor da oportunidade
Visualização única Visualização de lista

O guia a seguir pressupõe que você já conhece os conceitos básicos da Carteira do Google e já concluiu os pré-requisitos recomendados. Envie perguntas ou feedback para seu contato de operações de parceiro da Carteira do Google.

Etapas de integração

Para adicionar um novo módulo, você precisará atualizar o objeto e/ou a classe para incluir ValueAddedModuleData. O ValueAddedModuleData tem os seguintes campos:

[Required] Header LocalizedString

O cabeçalho exibido no módulo. O limite de caracteres é de 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 é de 50, e strings mais longas serão truncadas.
Exemplo de corpo de oportunidade de valor

Imagem da imagem

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

[Obrigatório] string uri

O URI de destino do módulo 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. Pode 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 será mostrado 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 mais baixo são mostrados antes dos módulos com um índice de classificação mais alto. Se não for 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, os módulos vão aparecer no cartão correspondente. Se você tiver adicionado apenas um módulo, ele vai aparecer na parte da frente do cartão.

Diretrizes sobre os módulos de oportunidades de valor agregado

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

  • Os módulos precisam ser definidos com linguagem apropriada para indicar que são acionáveis para ajudar os usuários a entender que eles são clicáveis.
  • Os módulos precisam ter as imagens apropriadas definidas relacionadas ao módulo específico.
  • Você está no controle dos módulos e precisa gerenciar proativamente a priorização deles, dependendo da importância e relevância.
  • Você só deve mostrar aos usuários módulos que estão ativos. Para controlar isso, defina o displayInterval no módulo ou adicione ou remova-o da classe ou do objeto de forma proativa.

Como processar exceções

Mensagem Motivo
O ValueAddedModuleData precisa conter um cabeçalho. O ValueAddedModuleData não tem um cabeçalho.
O ValueAddedModuleData precisa conter um URI não vazio. ValueAddedModuleData não tem um URI não vazio.
São permitidos no máximo 10 módulos de valor agregado por classe. É preciso reduzir os módulos de valor agregado na turma.
São permitidos no máximo 10 módulos de valor agregado por objeto. É necessário reduzir os módulos de valor agregado no objeto.