=========
`xMova Android <../doc.html>`_
=========

-------
Location
-------
``Versão 2.13+``

Permite que o aplicativo faça uso do serviço de localização da plataforma Android, enviando dados de posicionamento global para um Web Service.

``Versão 2.17+``
O parser cria as entidades Location, _GEOFENCE_LOCATION e _GEOFENCE_PLACE automaticamente quando não são declaradas no fluxo, permitindo que sejam usadas normalmente no fluxo mesmo sem a declaração explícita.
A velocidade enviada no registro da localização era data em m/s e agora está convertida para km/h


---------
Atributos:
---------

* ``tracking``: Habilita a funcionalidade de tracking
* ``geofence``: Habilita a funcionalidade de geofencing
* ``required``: Determina que para usar o aplicativo o usuário deve manter o GPS ativo no dispositivo, caso não esteja ativo é exibida uma mensagem de aviso que impede o usuário de utilizar o aplicativo.
* ``disableNotifyMessage``: Desabilita a mensagem que é exibida para notificar ao usuário que o GPS está desabilitado, esta mensagem só notifica o usuário e permite continuar utilizando o aplicativo mesmo com o GPS desabilitado.
* ``disableMotionDetection``: Desabilita a funcionalidade que inicia a obtenção de localização quando o sensor de acelerômetro identifica alguma movimentação no dispositivo. Este recurso só é habilitado quando o aplicativo está com a funcionalidade de **tracking** ou **geofence** ativada.
* ``disableSpeedVerification``: Faz com que o aplicativo interrompa a obtenção de localização para **tracking** e **geofence** sem verificar se os valores do atributo **maxLocationsWithMinSpeed** seja atingido.
* ``minTime``: Determina o tempo mínimo que o aplicativo deve aguardar para inciar a solicitação de uma nova localização. Caso o aplicativo esteja com a funcionalidade **tracking** ou **geofence** o comportamento é alterado se o dispositivo indicar movimento. Padrão: 10m (30m Versão 2.41.2)
* ``minLastTime``: Determina o tempo máximo de chache para que uma localização obtida ainda seja considerada válida. Padrão: 10m (30m Versão 2.41.2)
* ``minDistance``: Determina a distância mínima para que um registro de localização seja enviado quando a funcionalidade de **tracking** está habilitada. Padrão 1000m (5000m Versão 2.41.2)
* ``maxTriesForAccuracy``: Determina quantas localizações o aplicativo deve aguardar até que o valor de **minAccuracy** seja alcançado, caso o valor não seja alcançado é utilizada a localização com maior precisão. Padrão: 10
* ``minAccuracy``: Determina a precisão necessária para que uma localização seja aceita. Caso o valor do atributo **maxTriesForAccuracy** seja atingido então a precisão pode variar. Padrão 50m
* ``minSpeed``: Determina a velocidade mínima que o aplicativo deve considerar para continuar a receber localizações para as funcionalidades de **tracking** e **geofence**. Padrão: 0
* ``maxLocationsWithMinSpeed``: Determina quantas localizações com a velocidade mínima; definida em **minSpeed**, o aplicativo deve receber até que interrompa a funcionalidade de **tracking** e **geofence**. Padrão 5
* ``disableSpeak``: Desabilita a funcionalidade que fala as mensagens referentes ao serviço de localização.
* ``disableToast``: Desabilita a funcionalidade que exibe um Toast para exibir as mensagens referentes ao serviço de localização.

``Versão 2.17+``

* ``timeToNotifyStart``: Determina o tempo que o aplicativo deve aguardar até chamar o evento **OnMovimentStart**. A execução do evento pode ser cancelada durante o tempo de espera caso não for mais detectado movimento.
* ``timeToNotifyStop``: Determina o tempo que o aplicativo deve aguardar até chamar o evento  **OnMovimentStop**. A execução do evnto pode ser cancelada durante o tempo de espera caso seja detectado movimento.

``Versão 2.41.2+``

* ``minBearing``: Determina a diferença de angulação horizontal mínima entre os registros de tracking para serem enviados. Padrão 6

.. note::
   Quando é feito o uso do *tracking* o aplicativo avalia o tempo do último registro enviado (*minTime*), a distância entre o último registro enviado e o atual (*minDistance*) e a angulação horizontal (*minBearing*) e quando qualquer dos
   valores for satisfatórioé salvo o registro de localização como um registro de tracking.	

------
Langs :
------

* ``FixedKeyGeofenceTransitionEnter``: Falada e/ou exibida no Toast quando o valor do campo **enterText** da entidade _GEOFENCE_PLACE não está definido e o dispositivo entrou em uma área conhecida. Caso o valor da lang e do campo sejam vazios nenhuma mensagem é exibida. Podem ser usadas as tags <name> e <description> que serão substituidas pelos valores dos respectivos campos.
* ``FixedKeyGeofenceTransitionExit``: Falada e/ou exibida no Toast quando o valor do campo **exitText** da entidade _GEOFENCE_PLACE não está definido e o dispositivo saiu de uma área conhecida. Caso o valor da lang e do campo sejam vazios nenhuma mensagem é exibida. Podem ser usadas as tags <name> e <description> que serão substituidas pelos valores dos respectivos campos.
* ``FixedKeyGpsDisabledMessage``: Mensagem exibida quando o GPS está desabilitado. Padrão: Ative o GPS para que o aplicativo funcione corretamente.
* ``FixedKeyLocationService``: Título exibido na notificação que fica na barra de status quando o serviço de localização está ativo. Padrão: Serviço de Localização
* ``FixedKeyGettingLocation``: Mensagem exibida na notificação que fica na barra de status quando o aplicativo está obtendo a primeira localização. Padrão: Obtendo Localização

-------
Eventos:
-------

* ``onInsert``: Executado quando uma nova localização referente ao tracking é inserida no banco de dados. (Entidade: Location)

``Versão 2.17+``

* ``OnGeolocationTransitionEnter``: Executado quando o aplicativo entra em uma área conhecida. (Entidade: _GEOFENCE_LOCATION)
* ``OnGeolocationTransitionExit``: Executado quando o aplicativo sai de uma área conhecida. (Entidade: _GEOFENCE_LOCATION)
* ``OnMovimentStart``: Executado quando é detectado o início do movimento por meio da localização do GPS seguindo o parâmetro de **minSpeed**, declarado na configuração. Recebe os registro de **Location** (location), **_MARTE_STATUS** (marte) e **_GEOFENCE_LOCATION** (geofence) (Os dois últimos somente se o aplicativo possuir as funcionalides referentes a cada entidade)
* ``OnMoviment``: Executado enquanto é detectado movimento por meio da localização do GPS seguindo o parâmetro de **minSpeed**, declarado na configuração. Recebe os registro de **Location** (location), **_MARTE_STATUS** (marte) e **_GEOFENCE_LOCATION** (geofence) (Os dois últimos somente se o aplicativo possuir as funcionalides referentes a cada entidade) 
* ``OnMovimentStop``:  Executado quando é detectado que o movimento foi encerrado por meio da localização do GPS seguindo o parâmetro de **minSpeed**; somente é chamado se o evento **OnMovimentStart** tiver sido executado, declarado na configuração. Recebe os registro de Location, **Location** (location), **_MARTE_STATUS** (marte) e **_GEOFENCE_LOCATION** (geofence) (Os dois últimos somente se o aplicativo possuir as funcionalides referentes a cada entidade)

---------
Entidades:
---------

Entidade **Location** usada para inserir a informação de localização em algum apontamento e também para enviar registros de **tracking**.::

	Location sync=out
		lat double
		long double
		alt double
		gpsTime long
		speed float
		bearing float
		accuracy float

Entidade **_GEOFENCE_LOCATION** usada para inserir a informação de geofence em algum apontamento e também para enviar registros de **geofence**.::

	_GEOFENCE_LOCATION sync=out
		id inc
		place _GEOFENCE_PLACE inlineData
		location Location inlineData
		entered boolean


Entidade **_GEOFENCE_PLACE** usada para receber informações sobre locais que devem ser verificados nas rotinas de **geofence**.::
 
	_GEOFENCE_PLACE
		id int
		name String
		description String
		coordinates String
		notify String
		enterText String
		exitText String
		
``Versão 2.17+`` Entidade **_LOCATION_CONFIG** entidade que permite definir as configurações de **location** sem a necessidade de atualizar o fluxo (O fluxo deve ter uma configuração padrão de location para que possa usar esta entidade).::

	_LOCATION_CONFIG sync=in|backgroundIn
		id int
		tracking boolean
		geofence boolean
		notifyDisabled boolean
		gpsEnabledRequired boolean
		disableLocationSpeedVerification boolean
		disableDeviceMotionDetection boolean
		disableSpeak boolean
		disableToast boolean
		minTime int
		minLastTime int
		minDistance int
		maxTriesForAccuracy int
		minAccuracy int
		minSpeed float
		maxLocationsWithMinSpeed int
		timeToNotifyStop long
		timeToNotifyStart long

**Exemplo de Configuração**::

	App appCode=X
		id 30264
		name xMova Test
		version 1.0.157
		intVersion 158
		install type=fillAuth inputEntity=AuthInput
		camera resolution=61440 quality=100
	
		location
			tracking
			geofence
			minTime 1m
			minLastTime 5m
			minDistance 50
			maxTriesForAccuracy 13
			minAccuracy 5
			minSpeed 0
			maxLocationsWithMinSpeed 5
			
		OnMovimentStart
			toast @"Start Moviment"
			if hasFixedPoint == true
				toast location.speed
				Boletim boletim = SelectLast From Boletim		
				if boletim != null
					if location.speed >= boletim.minSpeed
						Object confirmResult = confirm text=@"Apontar Movimento?" backOnlyAfterNo timeout=boletim.timeout timeoutExceededValue=boletim.defaultValue
						if confirmResult == true
							crud ApontamentoMovimento
							return true
						else 
							return false
					else
						return false
				else
					return false
			else
				return false

		OnMoviment
			if hasFixedPoint == true
				Boletim bol = SelectLast From Boletim
				if bol != null
					if bol.showMovimentToast == true
						toast @"Moviment"
						toast location.speed

		OnMovimentStop
			toast @"Moviment Stopped"
			if hasFixedPoint == true
				toast location.speed
				Boletim boletim = SelectLast From Boletim		
				if boletim != null
					Object confirmResult = confirm text=@"Apontar Parada?" backOnlyAfterNo timeout=boletim.timeout timeoutExceededValue=boletim.defaultValue
					if confirmResult == true
						crud ApontamentoParada
						return true
					else
						return false
				else
					return false
			else
				return false

**Exemplo do envio da informação de um geofence pelo Web Service**::

	{
		"status": 0,
		"types": [{
			"name": "_GEOFENCE_PLACE",
			"records": [
			{
				"id": 15,
				"coordinates": "-23.193704,-45.893164;-23.193689,-45.892432;-23.193980,-45.892473;-23.193982,-45.893200",
				"name": "Simova 22",
				"description": "Simova Sala 22",
				"notify": "ENTER|EXIT",
				"enterText" : "Simova Sala 22",
				"exitText": "Fora da Simova 22"
			},{
				"id": 16,
				"coordinates": "-23.193980,-45.892473;-23.193982,-45.893200;-23.194209,-45.893228;-23.194218,-45.892476",
				"name": "Simova 24",
				"description": "Simova Sala 24",
				"notify": "ENTER|EXIT",
				"enterText" : "Simova Sala 24",
				"exitText": "Fora da Simova 24"
			}]
		}]
	}

**Exemplo de um registro de tracking**::

	{
		"type": "Location",
		"records": [{
			"lat": -23.193908333333336,
			"createDateTimeType": "S",
			"createDateTime": "01/12/2017 09:58:57",
			"XDATE-createDateTime": {
				"date": "01/12/2017 09:58:57",
				"gpsMillis": 1512129539224,
				"deviceMillis": 1512129540137,
				"timeZone": "America/Sao_Paulo",
				"type": "S",
				"millis": 1512129537400
			},
			"long": -45.892758333333326,
			"alt": 617.3,
			"gpsTime": 1512125940000,
			"speed": 0.0,
			"bearing": 290.07,
			"accuracy": 6.9
		}]
	}

**Exemplo de um registro de geofence**::

	{
		"type": "_GEOFENCE_LOCATION",
		"records": [{
			"id": 1,
			"createDateTimeType": "S",
			"createDateTime": "01/12/2017 09:58:57",
			"XDATE-createDateTime": {
				"date": "01/12/2017 09:58:57",
				"gpsMillis": 1512129539224,
				"deviceMillis": 1512129540137,
				"timeZone": "America/Sao_Paulo",
				"type": "S",
				"millis": 1512129537400
			},
			"place": {
				"id": 1,
				"name": "Simova22",
				"description": "Empresa Simova 22",
				"coordinates": "-23.193704,-45.893164;-23.193689,-45.892432;-23.193980,-45.892473;-23.193982,-45.893200",
				"notify": "ENTER|EXIT",
				"enterText": "Dentro da Simova 22",
				"exitText": "Fora da Simova 22"
			},
			"location": {
				"lat": -23.193908333333336,
				"createDateTimeType": "S",
				"createDateTime": "01/12/2017 09:58:57",
				"XDATE-createDateTime": {
					"date": "01/12/2017 09:58:57",
					"gpsMillis": 1512129539224,
					"deviceMillis": 1512129540137,
					"timeZone": "America/Sao_Paulo",
					"type": "S",
					"millis": 1512129537400
				},
				"long": -45.892758333333326,
				"alt": 617.3,
				"gpsTime": 1512125940000,
				"speed": 0.0,
				"bearing": 290.07,
				"accuracy": 6.9
			},
			"entered": 1
		}]
	}

**Exemplo de um Apontamento Enviado com Localização**::

	ApontamentoLocation sync=out
		id inc
		location Location inlineData
		text String
	
	{
		"type": "ApontamentoLocation",
		"records": [{
			"id": 1,
			"createDateTimeType": "S",
			"createDateTime": "04/12/2017 07:54:37",
			"XDATE-createDateTime": {
				"date": "04/12/2017 07:54:37",
				"gpsMillis": 1512381282438,
				"deviceMillis": 1512381284786,
				"timeZone": "America/Sao_Paulo",
				"type": "S",
				"millis": 1512381277427
			},
			"location": {
				"lat": -23.19423833,
				"createDateTimeType": "S",
				"createDateTime": "04/12/2017 07:54:29",
				"XDATE-createDateTime": {
					"date": "04/12/2017 07:54:29",
					"gpsMillis": 1512381274927,
					"deviceMillis": 1512381277275,
					"timeZone": "America/Sao_Paulo",
					"type": "S",
					"millis": 1512381269874
				},
				"long": -45.89276562,
				"alt": 575.0,
				"gpsTime": 1512381270000,
				"speed": 0.0,
				"bearing": 0.0,
				"accuracy": 7.0
			},
			"text": "test"
		}]
	}

**Exemplo de um Apontamento Enviado com Geofence e Localização**::

	ApontamentoGeofence sync=out
		id inc
		geofencePlace _GEOFENCE_LOCATION inlineData
		location Location inlineData
		text String
		
		
	{
		"type": "ApontamentoGeofence",
		"records": [{
			"id": 1,
			"createDateTimeType": "S",
			"createDateTime": "01/12/2017 10:02:14",
			"XDATE-createDateTime": {
				"date": "01/12/2017 10:02:14",
				"gpsMillis": 1512129736133,
				"deviceMillis": 1512129737031,
				"timeZone": "America/Sao_Paulo",
				"type": "S",
				"millis": 1512129734274
			},
			"geofencePlace": {
				"createDateTimeType": "S",
				"createDateTime": "01/12/2017 10:01:06",
				"XDATE-createDateTime": {
					"date": "01/12/2017 10:01:06",
					"gpsMillis": 1512129668233,
					"deviceMillis": 1512129669047,
					"timeZone": "America/Sao_Paulo",
					"type": "S",
					"millis": 1512129666273
				},
				"place": {
					"id": 1,
					"name": "Simova22",
					"description": "Empresa Simova 22",
					"coordinates": "-23.193704,-45.893164;-23.193689,-45.892432;-23.193980,-45.892473;-23.193982,-45.893200",
					"notify": "ENTER|EXIT",
					"enterText": "Dentro da Simova 22",
					"exitText": "Fora da Simova 22"
				},
				"location": {
					"lat": -23.193873333333332,
					"createDateTimeType": "S",
					"createDateTime": "01/12/2017 10:01:06",
					"XDATE-createDateTime": {
						"date": "01/12/2017 10:01:06",
						"gpsMillis": 1512129668233,
						"deviceMillis": 1512129669047,
						"timeZone": "America/Sao_Paulo",
						"type": "S",
						"millis": 1512129666273
					},
					"long": -45.89301833333334,
					"alt": 617.3,
					"gpsTime": 1512126067000,
					"speed": 0.0,
					"bearing": 256.27,
					"accuracy": 6.0
				},
				"entered": 1
			},
			"location": {
				"lat": -23.193873333333332,
				"createDateTimeType": "S",
				"createDateTime": "01/12/2017 10:01:06",
				"XDATE-createDateTime": {
					"date": "01/12/2017 10:01:06",
					"gpsMillis": 1512129668233,
					"deviceMillis": 1512129669047,
					"timeZone": "America/Sao_Paulo",
					"type": "S",
					"millis": 1512129666273
				},
				"long": -45.89301833333334,
				"alt": 617.3,
				"gpsTime": 1512126067000,
				"speed": 0.0,
				"bearing": 256.27,
				"accuracy": 6.0
			},
			"text": "test"
		}]
	}