Funcionalidades de localização na Extensão de Cartão Adaptável

Novos tipos de ação para geolocalização

Há duas ações de localização:

1. Obter Localização
2. Mostrar Local

Obter Localização:

Fornece o local atual do dispositivo do usuário ou abre o seletor de local nativo e retorna a localização escolhida pelo usuário. No navegador, ela usa o Bing Mapas como interface de mapeamento.

A ação ACE para Obter Localização é: VivaAction.GetLocation.

Ela usa um parâmetro booliano opcional: ChooseLocationOnMap.

Se a propriedade ChooseLocationOnMap for definida como true, a ação abrirá um mapa e o usuário poderá escolher um local no mapa; caso contrário, ela buscará a localização atual do dispositivo do usuário.

Mostrar Localização:

Com essa ação, um mapa é exibido na tela na qual você pode mostrar a localização atual do usuário no mapa ou mostrar as coordenadas especificadas no mapa.

A ação ACE para Mostrar Localização é: VivaAction.ShowLocation.

Ela usa um parâmetro de localização opcional: locationCoordinates.

Para mostrar uma localização específica, você deve passar as coordenadas de localização (latitude e longitude) por meio do parâmetro locationCoordinates.

O objeto locationCoordinates consiste nas seguintes propriedades:

{
  /**
   * Latitude of the location.
   */
  latitude: number;

  /**
   * Longitude of the location.
   */
  longitude: number;

  /**
   * Timestamp (optional).
   */
  timestamp?: number;

  /**
   * Accuracy of the location (optional).
   */
  accuracy?: number;
}

Tutorial e exemplos

Você pode dar uma olhada neste tutorial, que aborda os detalhes passo a passo de como você pode criar um cartão com ações de geolocalização.

Os exemplos a seguir descrevem a ação de geolocalização e sua finalidade.

1. Obter a localização atual do usuário

   Em seu JSON de modelo, introduza a seguinte ação:

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location'
   }]
   

   Quando essa ação é invocada, a geolocalização atual do usuário é buscada e é passada para o Desenvolvedor de Terceiros por meio do retorno de chamada onAction.

   Observação

   Nesse caso, o mapa não aparece.

2. Selecionar localização em um mapa

   Em seu JSON de modelo, introduza a seguinte ação:

   "actions": [{
     type: 'VivaAction.GetLocation',
     id: 'Get Location',
     parameters: {chooseLocationOnMap: true}
   }]
   

   Quando essa ação é invocada, um mapa apontando para a localização atual do usuário é aberto e o usuário pode selecionar e compartilhar a localização de sua escolha. As coordenadas da localização selecionada são passadas para o Desenvolvedor de Terceiros por meio do retorno de chamada onAction.

3. Exibir a localização atual do usuário

   Em seu JSON de modelo, introduza a seguinte ação:

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location'
   }]
   

   Quando essa ação é invocada, um mapa é aberto e as coordenadas de localização atuais do usuário são mostradas nele.

4. Exibir uma localização especificada

   Em seu JSON de modelo, introduza a seguinte ação:

   "actions": [{
     type: 'VivaAction.ShowLocation',
     id: 'Show Location',
     parameters: {
       locationCoordinates: {
         latitude: 28.6132039578389,
         longitude: 77.229488240066
       }
     }
   }]
   

   Quando essa ação é invocada, um mapa é aberto e mostra as coordenadas de localização especificadas na ação.

Acessar ações de geolocalização por meio do painel de propriedades do cartão do designer de cartão

Se você não quiser escrever código, mas ainda quiser ver como as ações de geolocalização funcionam, poderá explorar este tutorial que permite criar cartões com ações de geolocalização por meio do painel de propriedades.

Códigos de permissão e erro

Para que as APIs de localização funcionem, o usuário precisa conceder a permissão para acessar a localização do dispositivo.

Retornos de chamada para Desenvolvedores de cartão

Quando a ação VivaAction.GetLocation é invocada, passamos as coordenadas de localização buscadas por meio do retorno de chamada onAction.

Para ações: VivaAction.GetLocation e VivaAction.ShowLocation, se o usuário entrar em um estado de erro, um retorno de chamada onError será invocado, para o qual passaremos o nome da ação e o código de erro.

Disponibilidade de ações de geolocalização