Location SDK — Setup

Esta seção te guiará pelo processo de instalação e inicialização do Zapt Location SDK. No final, você poderá verificar se o SDK está funcionando corretamente e pronto para ser usado.

Android

Esta seção te guiará pelo processo de instalação e inicialização do Zapt Location SDK para Android. No final, você poderá verificar se o SDK está funcionando corretamente e pronto para ser usado.

Exemplo de implementação

Este app contém todos os passos abaixo implementados e funcionando. Utilize-o como referência durante a sua integração.

Requisitos Mínimos

Requisito	Versão
Java Compiler	1.8
Android SDK versão mínima (minSdkVersion)	Android API 21
Android Support Library v4	29+

Instalação

No arquivo build.gradle(:app) adicionar o repositório Maven da Zapt Tech bem como o jcenter. Em seguida, adicionar a dependência do Zapt Location SDK.

Antes de adicionar, verifique a versão mais atual do SDK aqui.

Gradle

repositories {
  ...
  maven {
      url 'https://zapt-mvn-repository.appspot.com'
      name 'Zapt Tech'
  }
  jcenter()
}

dependencies {
  ...
  implementation 'androidx.appcompat:appcompat:1.0.0'
  implementation 'tech.zapt:zapt-sdk:2.0.14'
}

Depois de atualizar o build.gradle do aplicativo, você deve sincronizá-lo para que as alterações entrem em vigor.

Inicialização

Java

import tech.zapt.sdk.location.ZaptSDK;

public class MainActivity extends Activity
{
  private WebView zaptWebView;
  private ZaptSDK zaptSDK;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.map);
    zaptWebView.setHostActivity(this);
    initializeZaptSDK();
    startWebView();
    listenBeacon();
  }

  public void initializeZaptSDK() {
    zaptSDK = ZaptSDK.getInstance(this);
    zaptSDK.requestPermissions(this);
    zaptSDK.verifyBluetooth(null, null);
    if (!zaptSDK.isInitialized()) {
      zaptSDK.initialize("PLACE_ID");
    }
  }

  public void startWebView() {
    // Add custom options in order to customize map behaviour
    Map<String, String> opts = new HashMap<>();
    opts.put("bottomNavigation", "false");

    // Get map link with the opts
    String url = zaptSDK.getMapLink(opts);

    // init Webview with the URL
    zaptWebView.loadUrl(url);
  }
}

É importante garantir que o ZaptWebView esteja configurado corretamente com o host activity para habilitar o funcionamento das orientações por voz.

Java

zaptWebView.setHostActivity(this);

Verifique que o SDK foi inicializado através do log:

Shell

Initialized Zapt SDK

PLACE_ID

Se você ainda não recebeu o identificador único do seu local (PLACE_ID), por favor entre em contato através do email contato@zapt.tech.

Declaração do ZaptWebView

Ao invés de utilizar o WebView tradicional para embutir o mapa, recomendamos o uso do ZaptWebView, que além de ser uma extensão do WebView, traz mais facilidades como o funcionamento das orientações por voz.

XML

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
>

  <tech.zapt.sdk.webapp.ZaptWebView
        android:id="@+id/webView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</LinearLayout>

Requisição de Permissão

Abaixo estão as permissões adicionadas automaticamente no AndroidManifest.xml pelo Zapt Location SDK.

XML

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
...
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-permission android:name="android.permission.INTERNET"/>

</manifest>

Observação

Para utilizar o Zapt Maps SDK em conjunto com Location SDK. Acesse a documentação aqui.

Escutando Beacons ao Redor - Opcional

Java

zaptSDK.addBeaconListener(new BeaconListener() {
  @Override
  public void onScan(Collection<Beacon> collection) {
    for (Beacon beacon : collection) {
      Log.i("zapt.tech", "Beacon Found: " + beacon.getDistance());
    }
  }
});

Identificação de Usuário - Opcional

É possível identificar usuários através dos atributos id e name; e segmentá-los através de categorias usando o atributo categories.

As categorias são agrupadas em um Map no qual a chave é o nome da categoria seguido pelo seu valor. Esses dados são apresentados no Zapt Analytics e também são enviados pela Webhook API.

Java

import tech.zapt.sdk.location.ZaptSDK;
import tech.zapt.sdk.location.ZaptUserInfo;

public class MainActivity extends Activity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        //...
        ZaptUserInfo userInfo = ZaptUserInfo.getInstance(this);
        userInfo.setUserName("Pedro Nunes");
        userInfo.getData().put("age", "30-40");
        userInfo.getData().put("departament", "IT");
        userInfo.getData().put("externalId", "93417");
        userInfo.commit();
    }
}

Alteração de Configurações Padrões - Opcional

Configurações como 'intervalo de sincronização com a nuvem' e 'habilitar modo debug' podem ser alterados através do objeto ZaptSDKOptions.

Java

import tech.zapt.sdk.location.ZaptSDK;
import tech.zapt.sdk.location.ZaptSDKOptions;

public class MainActivity extends Activity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        //...
        ZaptSDKOptions options = ZaptSDKOptions.getInstance();

        //enable logging
        options.setDebug(Boolean.TRUE);

        //Interval in ms to send data to the cloud
        options.setSyncInterval(60000);

        //Number of retries if request fails
        options.setHttpRetries(5);
    }
}

Recebendo Eventos em Background - Opcional

Para detectar beacons e receber eventos de localização quando o aplicativo está em segundo plano, é necessário configurar a inicialização do SDK no nível da Application, solicitar a permissão de localização em background e ajustar o intervalo de varredura em background.

O app de referência implementa essas etapas. Consulte os arquivos AppReferenceApplication.java, AndroidManifest.xml e MapViewActivity.java.

1. Permissão no AndroidManifest.xml

Além das permissões padrão do SDK, adicione a permissão de localização em background:

XML

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Registre também a classe Application customizada no elemento <application>:

XML

<application
    android:name=".AppReferenceApplication"
    ...>
</application>

2. Inicialização na Application

Crie uma subclasse de Application e inicialize o SDK em onCreate(). Isso garante que a varredura de beacons continue quando nenhuma Activity estiver em primeiro plano.

Java

import android.app.Application;

import java.util.Collection;

import tech.zapt.sdk.location.ZaptSDK;
import tech.zapt.sdk.location.ZaptSDKOptions;
import tech.zapt.sdk.location.beacon.Beacon;
import tech.zapt.sdk.location.beacon.BeaconListener;

public class AppReferenceApplication extends Application {

    private ZaptSDK locationSDK;

    @Override
    public void onCreate() {
        super.onCreate();

        ZaptSDKOptions sdkOptions = ZaptSDKOptions.getInstance();
        sdkOptions.setBackgroundBetweenScanPeriod(30000L);
        sdkOptions.setDebug(true);

        locationSDK = ZaptSDK.getInstance(this);
        if (!locationSDK.isInitialized()) {
            locationSDK.initialize("PLACE_ID");
        }

        locationSDK.addBeaconListener(new BeaconListener() {
            @Override
            public void onScan(Collection<Beacon> collection) {
                // Handle beacons detected in background
            }
        });
    }
}

O método setBackgroundBetweenScanPeriod define o intervalo, em milissegundos, entre varreduras quando o app está em background. O valor padrão de referência é 30000 (30 segundos).

3. Solicitação da permissão de background na Activity

Após o usuário conceder ACCESS_FINE_LOCATION, chame requestPermissionsBackground() para solicitar ACCESS_BACKGROUND_LOCATION. No Android 10 (API 29) e superior, essa permissão deve ser solicitada em um fluxo separado, depois da permissão de localização em primeiro plano.

Java

@Override
public void onRequestPermissionsResult(int requestCode,
                                       String permissions[], int[] grantResults) {
    switch (requestCode) {
        case PERMISSION_REQUEST_FINE_LOCATION: {
            if (grantResults != null && grantResults.length > 0
                    && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                AlertDialog.Builder builder = new AlertDialog.Builder(this);
                builder.setTitle("This app needs background location access");
                builder.setMessage("Please grant location access so this app can detect beacons in the background.");

                AlertDialog.Builder fnLimitedBuilder = new AlertDialog.Builder(this);
                fnLimitedBuilder.setTitle("Functionality limited");
                fnLimitedBuilder.setMessage("Since background location access has not been granted, this app will not be able to discover beacons in the background. Please go to Settings -> Applications -> Permissions and grant background location access to this app.");

                zaptSDK.requestPermissionsBackground(this, builder, fnLimitedBuilder);
            }
            return;
        }
        case PERMISSION_REQUEST_BACKGROUND_LOCATION: {
            if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Background location permission granted
            } else {
                // Inform the user that background detection is disabled
            }
            return;
        }
    }
}

Os diálogos passados para requestPermissionsBackground() explicam ao usuário por que a permissão é necessária e o que acontece caso ela seja negada. Personalize os textos conforme a experiência do seu app.

4. Testando eventos em background

Implante o aplicativo em modo release (./gradlew assembleRelease ou equivalente).
Desligue o beacon, reinicie o telefone e ligue o beacon novamente.
Com o app em background, os eventos de beacon ocorrem aproximadamente a cada 30 segundos.
Os logs podem ser acompanhados com adb logcat, filtrando pela tag do SDK.

Link de Localização em Mapas - Opcional

É possível visualizar no mapa configurado na Plataforma Zapt a localização em tempo real do usuário. Essa localização pode ser acessada através de links Web que podem ser embutidos em WebViews.

Java

String locationLink = zaptSDK.getMapLink();

Suporte a Arquiteturas 64-bits

Segundo a documentação oficial do Android para desenvolvedores:

A partir de 1º de agosto de 2019, seus apps publicados no Google Play precisarão ser compatíveis com arquiteturas de 64 bits.

E ainda, de acordo com a documentação oficial do Android para desenvolvedores:

Caso seu app use apenas código escrito na linguagem de programação Java ou Kotlin, incluindo quaisquer bibliotecas ou SDKs, ele já está pronto para dispositivos de 64 bits. Caso seu app use código nativo ou você não saiba se usa, avalie o app e tome as providências necessárias.

64 bits

A Zapt Location SDK é inteiramente desenvolvida em Java e/ou Kotlin. Sendo assim, compatível com arquiteturas 64-bits.

iOS

Esta seção te guiará pelo processo de instalação e inicialização do Zapt Location SDK para iOS. No final, você poderá verificar se o SDK está funcionando corretamente e pronto para ser usado.

Exemplo de implementação

Este app contém todos os passos abaixo implementados e funcionando. Utilize-o como referência durante a sua integração.

Requisitos Mínimos

Requisito	Versão
XCode	9.0+
Project target	iOS 9+
CocoaPods	1.2.0+

Instalação

Seu aplicativo deve usar CocoaPods para instalar o SDK. O CocoaPods gerencia dependências do seu projeto Xcode.

No arquivo Podfile adicione o pod ZaptLocation-iOS-SDK ao Podfile do seu projeto.

Antes de adicionar, verifique a versão mais atual do SDK aqui.

Ruby

pod 'ZaptLocation-iOS-SDK', '~>0.0.11-rc4'

Para habilitar o uso de bitcode, adicionar o seguinte código ao final do arquivo Podfile

Ruby

post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['BITCODE_GENERATION_MODE'] = 'bitcode'
            config.build_settings['ENABLE_BITCODE'] = 'YES'
        end
    end
end

No terminal, instale o pod e abra o arquivo .xcworkspace para ver o projeto no Xcode.

Shell

$ pod install
$ open your-project.xcworkspace

Requisição de Permissão

O SDK requer que determinados recursos sejam ativados em seu aplicativo para usar os serviços de localização. Para isso:

Edite o arquivo Info.plist, adicione as chaves NSLocationWhenInUseUsageDescription e NSLocationAlwaysUsageDescription. Os aplicativos destinados ao iOS 11 também exigem a chave NSLocationAlwaysAndWhenInUseUsageDescription. O valor dessas chaves é a mensagem que será exibida na tela do usuário quando solicitado a permitir o uso de serviços de localização. Para mais informações, consulte a página de documentação do Apple CoreLocation.

Observação

Para utilizar o Zapt Maps SDK em conjunto com Zapt Location SDK. Acesse a documentação aqui.

Inicialização

Objective-C

//File.h
#import <ZaptLocation_iOS_SDK/ZTLocationSDK.h>
//...
@property (retain) ZTLocationSDK *zaptSDK;

//File.m
self.zaptSDK = [[ZTLocationSDK alloc] initWithVisitableId:@"PLACE_ID"];
[self.zaptSDK start];

PLACE_ID

Se você ainda não recebeu o identificador único do seu local (PLACE_ID), por favor entre em contato através do email contato@zapt.tech.

Link de Localização em Mapas - Opcional

Objective-C

[self.zaptSDK getMapLink];

Escutando Beacons ao Redor

Beacons podem ser identificados usando o CoreLocation, API nativa do iOS. Ex.: https://developer.apple.com/documentation/corelocation/ranging_for_beacons

Identificação de Usuário - Opcional

É possível identificar usuários através dos atributos id e name; e segmentá-los através de categorias usando o atributo categories.

As categorias são agrupadas em um Map no qual a chave é o nome da categoria seguido pelo seu valor. Esses dados são apresentados no Zapt Analytics.

Objective-C

ZTUserInfo* userInfo = [ZTUserInfo recover];
[userInfo setUserName:@"Pedro Nunes"];

[userInfo.categories setValue: @"30-40" forKey:@"age"];
[userInfo.categories setValue: @"IT" forKey:@"departament"];
[userInfo commit];

React Native

Esta seção te guiará pelo processo de instalação e inicialização do Zapt Location SDK para React-Native. No final, você poderá verificar se o SDK está funcionando corretamente e pronto para ser usado.

Exemplo de implementação

A pasta examples deste repositório contém todos os passos abaixo implementados e funcionando. Utilize-a como referência durante a sua integração.

Requisitos Mínimos

A partir da versão 1.0.19 do zapt-tech/react-native-zapt-sdk, passa a ser obrigatória a utilização do React Native 0.73.0 ou superior.

Requisitos	Versão
React.js	16.8.1+
React Native	0.73.0+
React Native WebView (para IOS)	9.0.0+
XCode	9.0+
Project target	iOS 9+
CocoaPods	1.2.0+
Java Compiler	1.8
Android SDK versão mínima (minSdkVersion)	Android API 21
Android Support Library v4	26+

Instalação

Na pasta raiz do seu projeto rode: $ npm install @zapt-tech/react-native-zapt-sdk --save.

Para o funcionamento correto no componente ZaptMap em plataformas IOS, se faz necessária a instalação do pacote 'react-native-webview', que pode ser feita através do seguinte comando: npm i react-native-webview.

Versões mais recentes do React-Native efetuam o link virtual da bibliotecas de forma automática, caso esteja utilizando uma versão mais antiga ou seu projeto apresente erro na importação da biblioteca, tente:

Shell

$ npx react-native link react-native-zapt-sdk

Em Android, é necessário adicionar o ReactNativeZaptSdkPackage, na lista que é retornada no getPackages() na classe MainApplication.java ou MainApplication.kt.

Java

public class MainApplication extends Application implements ReactApplication {

  private final ReactNativeHost mReactNativeHost =
      new ReactNativeHost(this) {
        @Override
        public boolean getUseDeveloperSupport() {
          return BuildConfig.DEBUG;
        }

        @Override
        protected List<ReactPackage> getPackages() {
          @SuppressWarnings("UnnecessaryLocalVariable")
          List<ReactPackage> packages = new PackageList(this).getPackages();
          packages.add(new ReactNativeZaptSdkPackage());
          return packages;
        }

        @Override
        protected String getJSMainModuleName() {
          return "index";
        }
      };

      //...
  }

Para mais informações sobre esse procedimento, consulte a documentação oficial do React Native Modules.

Inicialização

Após feita a instalação conforme os passos acima, basta importar o pacote para dentro do arquivo desejado.

JavaScript

import { getMapLink, ZaptMap, requestPermissions } from '@zapt-tech/react-native-zapt-sdk';

Link para localização em mapas

A função apresentada logo abaixo disponibiliza um link que pode ser utilizado em um WebView ou componente de renderização de HTML semelhante. Esse link renderiza um mapa que mostra a localização do usuário em tempo real.

Observação

Devido a falta de suporte a síntese de voz no Webview nativo do android, quando o link é utilizado desta forma, algumas funcionalidades como assistente de voz durante a rota podem não funcionar, por esse motivo recomendamos fortemente o uso do componente ZaptMap.

JavaScript

getMapLink(placeID, {floorId: 1, displayButtonList: false, ...}, (mapLink) => {
  console.log(mapLink);
});

Componente ZaptMap

Também pode ser utilizado o componente ZaptMap que já traz o mapa de localização em tempo real pronto para integração com o APP.

JavaScript

class App extends Component {
  render(){
    return
      (<ZaptMap
        placeID={<String>}
        options={{floorId: 1, displayButtonList: false, ...}}
      />);
    }
  }

Nota

Tanto na função getMapLink quanto no componente ZaptMap, o parâmetro placeID é necessário para o funcionamento do componente. Se você ainda não recebeu o identificador único do seu local (PLACE_ID), por favor entre em contato através do email contato@zapt.tech.

Requisição de Permissões

Assim que o Mapa é inicializado pela primeira vez no APP será requisitada permissão para acesso a localização do dispositivo, mas se necessário essa permissão pode ser requisitada em um momento anterior através da função requestPermissions().

Escutando Evento de Localização

É possível escutar eventos de localização através do método: addLocationListener(placeID, locationCallback).

A locationCallback é invocada com o seguinte objeto:

floorId	Integer	Id. do andar da localização
xy	Array	Coordenadas XY da localização
nearestPoi	Objeto	Ponto de Interesse mais próximo da localização atual
nearestBeacon	Objeto	Beacon mais próximo da localização atual

Exemplo de uso:

JavaScript

import { addLocationListener } from '@zapt-tech/react-native-zapt-sdk';

addLocationListener(placeID, (location) => {
  console.info(location);
});

// objeto que será impresso
{
  "floorId": 1,
  "xy": [1830, 1540]
  "nearestPoi": {
    "categoryId": 5767574868459520,
    "floor": "1",
    "id": "-mtcg0mphsnqdrpc-ohk",
    "isTemporal": false,
    "tags": ["caixa econômica federal"],
    "text": "Banco Caixa - LOCALIZADO NO PISO 1",
    "title": "CAIXA ECONÔMICA FEDERAL",
    "x": 1870,
    "xy": "1870_1680",
    "y": 1680,
    "externalId": "510"
  }
}

Parar de Escutar Eventos de Localização

Para parar de escutar eventos de localização iniciados pelo método mencionado acima, basta chamar o método: removeLocationListener().

Exemplo de uso:

JavaScript

import {removeLocationListener} from '@zapt-tech/react-native-zapt-sdk';

removeLocationListener()

Recebendo Eventos em Background

Para receber eventos em background é necessário chamar o método: requestPermissionsBackground().

Em iOS, é necessário adicionar a entrada Privacy - Location Always Usage Description no Info.plist.

Em Android, é necessário adicionar a entrada <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/> no MANIFEST.MF.

Exemplo de uso:

JavaScript

import React, { Component } from 'react';
import { NativeModules, NativeEventEmitter } from 'react-native';
import {initialize, requestPermissionsBackground, getMapLink, ZaptMap, addLocationListener } from '@zapt-tech/react-native-zapt-sdk';

initialize(placeID).then(() => {
  requestPermissionsBackground().then(() => {
    const eventEmitter = new NativeEventEmitter(NativeModules.ReactNativeZaptSdk);

    eventEmitter.addListener('ReactNativeZaptSdkBeaconsFound', (event) => {
      console.info('beacon found event');
    });

    eventEmitter.addListener('ReactNativeZaptSdkBeaconsRegionExit', (event) => {
      console.info('ReactNativeZaptSdkBeaconsRegionExit');
    });

    eventEmitter.addListener('ReactNativeZaptSdkBeaconsRegionEnter', (event) => {
      console.info('ReactNativeZaptSdkBeaconsRegionEnter');
    });
  });
});

Em Android, eventos em background chegarão como HeadlessTask:

JavaScript

//...
import { AppRegistry } from 'react-native';
import { calculateLocation } from '@zapt-tech/react-native-zapt-sdk';
//...
AppRegistry.registerHeadlessTask('ReactNativeZaptSdkBeaconsFound', () => {
  return function(data){
    return new Promise(async (resolve) => {
      console.info('JS ReactNativeZaptSdkBeaconsFound', data);
      if(data && data.beacons) {
        //do your stuff here or get the location like below
        try {
          let beacons = JSON.parse(data.beacons);
          let location = await calculateLocation(placeID, beacons);
          if(location) {
            console.info('Location found', location);
          }
        } catch(e) {
          console.error(e);
        }
      }
      resolve();
    });
  }
});

Em Android, também é necessário adicionar a inicialização do ReactNativeZaptSDK, como variável de instância, no MainApplication.java.

Java

public class MainApplication extends Application implements ReactApplication {

  private ReactNativeZaptSDK reactNativeZaptSDK;

  //...

  @Override
  public void onCreate() {
    Log.d("tech.zapt.example", "Creating app");
    super.onCreate();
    reactNativeZaptSDK = ReactNativeZaptSDK.getInstance(this, this);
    SoLoader.init(this, /* native exopackage */ false);
    initializeFlipper(this, getReactNativeHost().getReactInstanceManager());
  }
  //...
}

Em iOS, também é necessário adicionar modo background:

Configuração de Background Modes no Xcode para receber eventos em segundo plano no iOS. — Background Modes no Xcode para iOS.

Em iOS, para testar eventos em background, implante sua aplicação em modo release, desligue o beacon, reinicie o telefone e na sequencia ligue o beacon. O evento ReactNativeZaptSdkBeaconsRegionEnter tem que ser enviado.

Em iOS, para debugar eventos em background no iOS, abre o XCode, marque o código a ser inspecionado e selecione: Debug > Attach to process > [select your process].

Em Android, para testar eventos em background, implante sua aplicação em modo release npx react-native run-android --variant=release , desligue o beacon, reinicie o telefone e na sequencia ligue o beacon. A task ReactNativeZaptSdkBeaconsRegionEnter tem que ser enviada.

Em Android, logs em background podem ser vistos com o comando npx react-native log-android.

Em Android, eventos de localização indoor acontecem aproximadamente a cada 30s.

Importante

Em ambas plataformas, todos os testes devem ser feitos em dispositivos (smartphones) reais.

Opções de Layout

Tanto a função getMapLink (segundo parâmetro) quanto o componente ZaptMap (prop options) aceitam opções para personalizar a visualização do mapa.

Nome	Tipo	Predefinição	Descrição
bottomNavigation	bool	true	Se true mostra a barra inferior
appBar	bool	true	Se true mostra a barra superior
displayZoomButton	bool	true	Se true mostra os botões de zoom
displayFloorsButton	bool	true	Se true mostra o botão para troca de andares
search	bool	true	Se true mostra o campo de pesquisa (em telas grandes)
splash	bool	true	Se true mostra um splash da Zapt Tech, se false mostra um splash genérico
navBar	bool	true	Se true mostrar a barra de navegação
embed	bool	false	Se true remove todas as opção, apresentando apenas o mapa

Opções Funcionais

Além das opções de layout o atributo options também recebe opção para funcionalidades do mapa.

Nome	Tipo	Descrição
floorId	string	Recebe o ID do andar em que o mapa deve ser inicializado. Consulte esse ID no Zapt Portal.
zoom	number	Defini o zom inicial do mapa. O valor de zoom precisa estar entro o limite mínimo e máximo definidos na configura do mapa.
rotation	number	Define um angulo inicial de rotação do mapa. Este valor pode estar entre 0 e 360.
poi	string	Recebe e ID de um ponto de interesse e centraliza o mapa sobre o mesmo. Consulte esse ID no Zapt Portal.
Centralizar por Coordenadas
centerX	number	Defini o centro inicial do mapa na horizontal
centerY	number	Defini o centro inicial do mapa na horizontal
Nota: Os atributos `centerX` e `centerY` precisam ser utilizados em simultâneo para funcionarem.
Traçar rotas com pontos de interesse
fromPoi	string	ID de um ponto de interesse para o inicio de uma rota.
toPoi	string	ID de um ponto de interesse para o inicio de uma rota.
É possível adicionar somente o parâmetro do ponto de destino. Nesse caso a rota será traçada a partir da entrada principal, se houver. Se apenas o ponto de partida estiver inserido, nada acontecerá.
Traçar rotas com coordenadas
fromCoordinateX	number	Coordenada X (horizontal) para origem da rota
fromCoordinateY	number	Coordenada Y (vertical) para origem da rota
fromCoordinateZ	number	Coordenada Z (andar) para origem da rota
toCoordinateX	number	Coordenada X (horizontal) para destino da rota
toCoordinateY	number	Coordenada Y (vertical) para destino da rota
toCoordinateZ	number	Coordenada Z (andar) para destino da rota
É possível adicionar somente o parâmetro do ponto de destino. Nesse caso a rota será traçada a partir da entrada principal, se houver. Se apenas o ponto de partida estiver inserido, nada acontecerá.
Desenhar marcador
markerX	number	Coordena X (horizontal) para onde marcador deve ser desenhado.
markerY	number	Coordena Y (horizontal) para onde marcador deve ser desenhado.
markerZ	number	Coordena Z (andar) onde marcador deve ser desenhado.

Flutter

Esta seção te guiará pelo processo de instalação e inicialização do Zapt Location SDK para Flutter. No final, você poderá verificar se o SDK está funcionando corretamente e pronto para ser usado.

Exemplo de implementação

Este repositório contém todos os passos abaixo implementados e funcionando. Utilize-o como referência durante a sua integração.

Requisitos Mínimos

Requisitos	Versão
Flutter	3.0.0+
Xcode	14.0+
Alvo de implantação iOS	iOS 13.0+
Swift Package Manager (SPM)	Recomendado
CocoaPods	Opcional (1.2.0+) — não recomendado
Java Compiler	17
Android SDK versão mínima (minSdkVersion)	Android API 21

Instalação

Na pasta raiz do seu projeto rode: $ flutter pub add zapt_sdk_flutter.

Na pasta your-project/android/app/build.gradle modificar o minSdkVersion para 21.

Gradle

android {
  ...
  defaultConfig {
    ...
    minSdkVersion 21
    ...
  }
}

Edite o arquivo your-project/ios/Runner/Info.plist adicionando as seguintes entradas:

NSLocationWhenInUseUsageDescription
NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationAlwaysUsageDescription

O valor dessas chaves é a mensagem que será exibida na tela do usuário quando solicitado a permitir o uso de serviços de localização. Para mais informações, consulte a página de documentação do Apple CoreLocation.

Integração iOS

A partir da versão 2.1.0, a camada nativa iOS é integrada via Swift Package Manager (SPM). Este é o caminho recomendado e padrão para novos projetos.

Ao adicionar este plugin e executar flutter pub get, o Flutter resolve as dependências iOS via SPM automaticamente — na maioria dos casos, nenhuma configuração nativa extra é necessária.

Swift Package Manager (recomendado)

Garanta que seu app tenha como alvo iOS 13.0+.
Use Flutter 3.0+ com uma versão recente do Xcode.
Compile normalmente com flutter run ou flutter build ios.

O plugin declara seu pacote iOS em ios/zapt_sdk_flutter/Package.swift, que inclui o ZaptLocation-iOS-SDK e as dependências necessárias do plugin Flutter.

CocoaPods (opcional, não recomendado)

O suporte a CocoaPods permanece disponível via ios/zapt_sdk_flutter.podspec para projetos legados que ainda dependem de um Podfile.

CocoaPods

Não recomendamos CocoaPods para novas integrações. O registro trunk do CocoaPods está planejado para se tornar somente leitura — nenhuma nova versão de pod será aceita após dezembro de 2026. Builds existentes podem continuar funcionando, mas dependências distribuídas apenas via CocoaPods deixarão de receber atualizações. Prefira SPM para todo trabalho novo.

Se precisar permanecer no CocoaPods, mantenha o CocoaPods 1.2.0+ e seu fluxo existente de pod install.

Inicialização

Após feita a instalação conforme os passos acima, basta importar o pacote para dentro do arquivo desejado.

Dart

import 'package:zapt_sdk_flutter/zapt_sdk_flutter.dart';

Widget ZaptMap

O Widget ZaptMap é a opção recomendada que já traz o mapa e a localização em tempo real integrados e prontos para uso no APP. Segue abaixo um exemplo de implementação:

Dart

import 'package:zapt_sdk_flutter/zapt_sdk_flutter.dart';

class Example extends StatefulWidget {
  const Example({Key? key}) : super(key: key);

  @Override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  Map<String, String> options = {'floorId': '1'};
  final String placeId = "-ltvysf4acgzdxdhf81y";

  @Override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: ZaptMap(
        placeId: placeId,
        options: options, //optional
        onCreated: (controller) => setState((){
          _controller = controller,
        }),
      ),
    );
  }
}

Nota

Tanto a função getMapLink quanto o Widget ZaptMap, o parâmetro placeID é necessário para o funcionamento. Se você ainda não recebeu o identificador único do seu local (PLACE_ID), por favor entre em contato através do email contato@zapt.tech.

Controller - Interagindo com o mapa

O Widget ZaptMap retorna um controller através da callback onCreated, como apresentado no exemplo acima. Esse controller oferece métodos de interação com o mapa.

Nome	Funcionalidade
Mudar de Andar
setFloor	Este método retorno uma `Future` que é resolvida assim que o novo andar é inicializado.
`zaptController.setFloor(0)`
setMapId	Este método retorno uma `Future` que é resolvida assim que o novo mapa é inicializado.
`zaptController.mapId("-ltvysf4acgzdxdhf81y-floor0")`
Centralizar
setCenter	Centraliza o mapa de acordo com uma instancia de `MapCenter` com coordenadas horizontal(x) e vertical(y). Pode-se passar o zoom como atributo ou defini-lo mais tarde.
`zaptController.setCenter(MapCenter(x:100, y:100, zoom: 0));`
highlightInterestById	Recebe como parâmetro o id único do POI e centraliza o mapa nas coordenadas do POI.
`zaptController.highlightInterestById("-mtcd5jwpv3bukpewpu_");`
removeHighlightInterest	Remove o foco do POI, recebe como parâmetro um `bool` que quando `true` volta o mapa para o centro e zoom inicial.
`zaptController.removeHighlightInterest();`
Definir zoom
setZoom	Recebe como parâmetro o valor do zoom. Esse valor deve ser mínimo ≤ zoom ≤ máximo, onde o mínimo e o máximo são definidos na configuração do mapa.
`zaptController.setZoom(0);`
Rotacionar o mapa
setRotation	Recebe como parâmetro o valor do ângulo em graus.
`zaptController.setRotation(180);`
Iniciar Rota
createRouteByIds	Traça uma rota entro dois POIs recebendo como parâmetro os ids dos pontos de interesse de origem e de destino respectivamente.
`zaptController.createRouteByIds("-mtc1mhp6t5hwg9zdidy", "-ltfb2qqdg6jgwqhf1_i");`
createRouteByCoordinates	Recebe como parâmetro uma instancia de `ReferencePoint` para a origem e uma para o destino
`zaptController.createRouteByIds(ReferencePoint(coordX: 340, coordY: 1130, floor: 1), ReferencePoint(coordX: 340, coordY: 1130, floor: 1));`
removeRoute	Remove a rota traçada.
`zaptController.removeRoute();`

Monitorando Eventos do Mapa

No Widget ZaptMap é possível passar callbacks para ouvir eventos do mapa:

onChangeMapStatus

Através dessa callback é possível receber o estado de loading do mapa assim que ele inicia ou termina de inicializar.

Dart

ZaptMap(
  ...
  onChangeMapStatus: (loading) => setState((){
    _mapIsLoading = loading;
  }),
)

onMapStartsLoading

Essa callback é chamada toda vez que um mapa começa a carregar. Recebe como parâmetros o ID do visitável, o ID do andar que será carregado, o nome do andar que será carregado e o status de carregamento do mapa.

Dart

ZaptMap(
  ...
  onMapStartsLoading: (mapInfo) {
    debugPrint("Changing to floor name: ${mapInfo.floorName}");
    debugPrint("Changing to floor ID: ${mapInfo.floorId}");
    debugPrint("Changing to place ID: ${mapInfo.placeId}");
  },
)

onMapFinishesLoading

Essa callback é chamada toda vez que um mapa termina de carregar. Recebe como parâmetros o ID do visitável, o ID do andar que foi carregado, o nome do andar que foi carregado e o status de carregamento do mapa.

Dart

ZaptMap(
  ...
  onMapFinishesLoading: (mapInfo) {
    debugPrint("Loaded on floor name: ${mapInfo.floorName}");
    debugPrint("Loaded on floor ID: ${mapInfo.floorId}");
    debugPrint("Loaded on place ID: ${mapInfo.placeId}");
  },
)

onCancelRoute

Essa callback é chamada toda vez que uma rota é cancelada.

Dart

ZaptMap(
  ...
  onCancelRoute: ()=> debugPrint("Route canceled"),
)

onMapClick

Essa callback é chamada quando o mapa é clicado. Recebe como parâmetros o POI mais próximo do click, as coordenadas do ponto exato onde o mapa foi clicado e como terceiro parâmetro se o click foi dentro da área do POI.

Ao passar uma função para essa callback o comportamento padrão de abrir uma popup no POI clicado deixa de acontecer.

Dart

ZaptMap(
  ...
  onMapClick: (interestClicked, clickedPoint, clickInsidePOI) {
    debugPrint("Interest Id clicked ${interestClicked.id}");
    debugPrint("Clicked inside POI area $clickInsidePOI");
    debugPrint(
        "Clicked point: X: ${clickedPoint.x}  Y: ${clickedPoint.y}");
  },
)

Requisição de Permissões

Link para localização em mapas (opcional)

A função apresentada logo abaixo disponibiliza um link que pode ser utilizado em um WebView ou Widget de renderização de HTML semelhante. Esse link renderiza um mapa que mostra a localização do usuário em tempo real.

Observação

Dart

final _zaptSdkFlutterPlugin = ZaptSdkFlutter();
Map<String, String> options = {'floorId': '1'};
final String placeId = "-ltvysf4acgzdxdhf81y";

String mapLink = ""
mapLink = await _zaptSdkFlutterPlugin.getMapLink({'placeId': placeId, 'options': options});

Troubleshooting (Erros conhecidos)

Se você estiver tendo o seguinte erro ao realizar a implantação em iOS com CocoaPods:

Shell

error: include of non-modular header inside framework module 'zapt_sdk_flutter.ZaptSdkFlutterPlugin'

Verifique a solução neste link. Este problema não se aplica quando se utiliza a integração SPM recomendada.

Opções de Layout

Tanto a função getMapLink (segundo parâmetro) quanto o Widget ZaptMap (prop options) aceitam opções para personalizar a visualização do mapa.

Nome	Tipo	Predefinição	Descrição
bottomNavigation	bool	true	Se true mostra a barra inferior
appBar	bool	true	Se true mostra a barra superior
displayZoomButton	bool	true	Se true mostra os botões de zoom
displayFloorsButton	bool	true	Se true mostra o botão para troca de andares
search	bool	true	Se true mostra o campo de pesquisa (em telas grandes)
splash	bool	true	Se true mostra um splash da Zapt Tech, se false mostra um splash genérico
navBar	bool	true	Se true mostrar a barra de navegação
embed	bool	false	Se true remove todas as opções, apresentando apenas o mapa

Opções Funcionais

Além das opções de layout o atributo options também recebe opção para funcionalidades do mapa.

Nome	Tipo	Descrição
floorId	string	Recebe o ID do andar em que o mapa deve ser inicializado. Consulte esse ID no Zapt Portal.
zoom	number	Defini o zom inicial do mapa. O valor de zoom precisa estar entro o limite mínimo e máximo definidos na configura do mapa.
rotation	number	Define um angulo inicial de rotação do mapa. Este valor pode estar entre 0 e 360.
poi	string	Recebe e ID de um ponto de interesse e centraliza o mapa sobre o mesmo. Consulte esse ID no Zapt Portal.
Centralizar por Coordenadas
centerX	number	Defini o centro inicial do mapa na horizontal
centerY	number	Defini o centro inicial do mapa na horizontal
Nota: Os atributos `centerX` e `centerY` precisam ser utilizados em simultâneo para funcionarem.
Traçar rotas com pontos de interesse
fromPoi	string	ID de um ponto de interesse para o inicio de uma rota.
toPoi	string	ID de um ponto de interesse para o inicio de uma rota.
É possível adicionar somente o parâmetro do ponto de destino. Nesse caso a rota será traçada a partir da entrada principal, se houver. Se apenas o ponto de partida estiver inserido, nada acontecerá.
Traçar rotas com coordenadas
fromCoordinateX	number	Coordenada X (horizontal) para origem da rota
fromCoordinateY	number	Coordenada Y (vertical) para origem da rota
fromCoordinateZ	number	Coordenada Z (andar) para origem da rota
toCoordinateX	number	Coordenada X (horizontal) para destino da rota
toCoordinateY	number	Coordenada Y (vertical) para destino da rota
toCoordinateZ	number	Coordenada Z (andar) para destino da rota
É possível adicionar somente o parâmetro do ponto de destino. Nesse caso a rota será traçada a partir da entrada principal, se houver. Se apenas o ponto de partida estiver inserido, nada acontecerá.
Desenhar marcador
markerX	number	Coordena X (horizontal) para onde marcador deve ser desenhado.
markerY	number	Coordena Y (horizontal) para onde marcador deve ser desenhado.
markerZ	number	Coordena Z (andar) onde marcador deve ser desenhado.