Invocar Navigation Global desde otras aplicaciones

Es posible llamar a Verizon Connect Navigation Global Edition (NavGE) con otras aplicaciones para proporcionar orientación sobre la ruta a destinos aportados por dichas aplicaciones. Debido a que NavGE requiere de autenticación, la aplicación de llamada debe proporcionar información de autenticación antes de poder utilizarse. La autenticación adopta la forma de un token TDE y un nombre de usuario. Todos los datos se transmiten como pares de valor clave (KVP), pero el mecanismo depende del sistema operativo.

En lo que respecta a Android, la llamada se realiza con una intención explícita y todos los datos se transmiten como KVP (llamados datos "adicionales" en un sistema operativo Android) en la intención. En cuando a iOS, la mayoría de los datos se transmiten en la URL bajo un esquema de URL, en tanto que los datos adicionales se transmiten en la mesa de trabajo de iOS.

Datos de invocación

Tipo de comando

command=[login|navigate]
El comando login ejecuta Navigation o lo trae a un primer plano, y valida los datos KVP de autenticación.

El comando navigate ejecuta Navigation o lo trae a un primer plano, y usa los datos de KVP de ajuste de destinos y ruta opcional para calcular una ruta. Si se proporcionan, también valida los datos KVP de autenticación.

Especificación del banner

Los parámetros del banner le permiten reservar las partes superior o inferior (o ambas) de la pantalla para su personalización (por ejemplo, iconos de un sistema de cliente específico). De manera predeterminada, la aplicación Navigation llena la pantalla completa.

TopPadding = altura del banner superior en DIP (Dispositivo-Independiente-Unidad.
BottomPadding = altura del banner inferior en DIP.

Autenticación

Autenticación TDE:

tdetoken = token tal como se recibe de una solicitud de autenticación de TDE.
tokenexpiry = la fecha de vencimiento de tdetoken (e formato ISO 8601, zona horaria UTC) tal como se recibe de la solicitud de autenticación de TDE.
user = nombre de usuario en formato de usuario de Fleet (company:driver) utilizado para adquirir el tdetoken.

Autenticación con token STSv4 de Verizon Connect Reveal

En lugar de un token TDE, Navigation puede aceptar un token STSv4 de Reveal.

externaltoken = valor de cadena que contiene el valor del token, de manera opcional con prefijo de identificador de región y el carácter "-", por ejemplo, "UE-" para Europa. Si se omite el prefijo, se asume que corresponde a la región de EE. UU.
externaltokentype = "VZCSMB" para token Reveal/STSv4.

Destino

NavGE comprueba los parámetros de destino en el siguiente orden: site, locationid, latitude y longitude, address. Tan pronto se detecta el parámetro, el resto pueden ignorarse. Si no se detectan parámetros, NavGE informa un error.

Opción 1: Los datos del sitio de la ubicación se encuentran en formato JSON.

site = Para Android, es una cadena JSON en formato de un Sitio TDE. Para iOS, se trata de una clave que apunta a una cadena de JSON de un sitio TDE de la mesa de trabajo de iOS. Se utiliza
site en preferencia a latitude/longitude. Suele preferirse esto por dos motivos principales:

La especificación completa de un sitio TDE se encuentra fuera del alcance de este documento. Sin embargo, los elementos mínimos de sitio requeridos para utilizar con NavGE son los siguientes:

Un valor ID (0 excepto que los datos del sitio correspondan a un registro real de Fleet Site).
Punto de ubicación.
Un miembro del conjunto de direcciones con un número de calle (si se conoce) y un nombre de calle.

Opción 2: Id. del marcador del cliente.

locationid = Id. del marcador de un cliente. Se utiliza locationid para buscar el marcador y descargar la información del marcador, que luego se utiliza para generar una ruta a la ubicación.

Opción 3: latitud y longitud de la ubicación.

latitude = Debe proporcionarse junto con longitude.
longitude = Debe proporcionarse junto con latitude.

Opción 4: dirección textual de la ubicación.

address = Dirección textual.

Ajustes de ruta

hazmat = (opcional) Ofrece una lista de códigos de hazmat (materiales peligrosos) que corresponden a un ajuste de hazmat, separados por comas para habilitarse para la ruta. Para más información, consulte Nueve clases de materiales peligrosos.

Dimensiones del vehículo

dimensionunits = (opcional) Unidad de medida preferida para la dimensión del vehículo. No distingue entre mayúsculas y minúsculas. Los valores válidos son 'm' y 'ft', para metros y pies, respectivamente.
length = (opcional) Extensión del vehículo. Para números decimales, ingrese un punto para un punto decimal (no hay coma disponible). Este valor se ignorará si falta 'dimensionunits' o si este no es válido. El rango de valor válido es 8 ft a 10 000 ft.
width = (opcional) Ancho del vehículo. Para números decimales, ingrese un punto para un punto decimal (no hay coma disponible). Este valor se ignorará si falta 'dimensionunits' o si este no es válido. El rango de valor válido es 2 ft a 500 ft.
height = (opcional) Altura del vehículo. Para números decimales, ingrese un punto para un punto decimal (no hay coma disponible). Este valor se ignorará si falta 'dimensionunits' o si este no es válido. El rango de valor válido es 2 ft a 100 ft.
weightunit = Unidad de medida de preferencia para el peso del vehículo. Los valores válidos son 'lb' y 'kg' para libras y kilogramos, respectivamente.
grossweight = Peso bruto del vehículo, que incluye el peso del vehículo y la carga. Para números decimales, ingrese un punto para un punto decimal (no hay coma disponible). Se ignorará este valor si 'weightunit' falta o no es válido. El rango de valor válido es 10 000 lb a 500 000 lb.

Comportamiento regresar a la aplicación

Navigation regresa a la aplicación de llamada en los siguientes casos:

Se completó la ruta al llegar a destino.
El usuario toca la flecha de retroceso en la pantalla Descripción general de la ruta.

Para habilitar esta funcionalidad en iOS, debe definirse la propiedad appId en la solicitud de navegación. Cuando Nav regresa a la aplicación de llamada, se abre una URL con el valor appId si el valor se encuentra en la lista compatible con Nav (valores admitidos: TelogisWorkplan). Por ejemplo, si appId=MyApp, Nav abre la URL MyApp://. La aplicación de llamada debería registrarse en iOS para abrir URL con ese patrón.

Para Android, no se necesitan medidas para habilitar esta funcionalidad. En los casos de arriba, Nav se envía a sí misma a un segundo plano.

Comportamiento de autenticación de la API

Navigation comprueba la presencia de datos de autenticación válidos cuando recibe una intención.

Para solicitudes de intención con command=login, se requieren datos de autenticación. Para solicitudes con command=navigate, el comportamiento de Navigation depende de los datos de la intención y del estado actual de la aplicación. En la siguiente tabla, se describen los posibles resultados:

Navigation ya está autenticada
La intención contiene datos de autenticación	Comprobar y utilizar nuevos datos de autenticación de intenciones
La intención omite los datos de autenticación	Mantener la autenticación existente de Navigation
Navigation no está autenticada
La intención contiene datos de autenticación	Comprobar y utilizar datos de la intención
La intención omite los datos de autenticación	Mostrar página de inicio de sesión

Si Navigation ya está autenticada y recibe una intención con datos de autenticación válidos, Navigation cambia al usuario especificado en la intención. Si no puede completarse el cambio de usuario, Navigation regresa a la página de inicio momentáneamente antes de regresar al usuario original.

Ejemplos de código

Android

La solicitud debería enviarse a NavGE mediante una intención de Android. NavGE se ubica en primer plano cuando se recibe la intención.

El nombre de paquete de NavGE es "com.telogis.nav6". Puede utilizarse para lanzar NavGE y aprobar parámetros de solicitud en NavGE.

Ejemplos de código

Los siguientes son ejemplos Java. Otra manera habitual de probar intenciones en Android es invocar al Administrador de actividades del dispositivo mediante el uso de adb.

Solicitud de inicio de sesión:

Intent intent = getPackageManager().getLaunchIntentForPackage("com.telogis.nav6"); intent.PutExtra("command", "login"); intent.PutExtra("user", "FleetName:Username"); intent.PutExtra("tokenexpiry", "2020-09-29T18:00:00Z"); intent.PutExtra("tdetoken", "Token");

// Ejecutar NavGE y transmitir parámetros de solicitud startActivity(launchIntent);

A través del Admininistrador de actividades de ADB (línea de comando Linux/MacOS):

adb shell 'am start -a android.intent.action.MAIN -n "com.telogis.nav6/telogis.navigation.MainActivity" -e command login -e user "examlcustmr:exampldrvr" -e tdetoken "tokendata" -e tokenexpiry "YYYY-MM- DThh:mm:ssZ"'

A través del Administrador de actividades de ADB (línea de comando Windows):

adb shell ""am start -a android.intent.action.MAIN -n "com.telogis.nav6/telogis.navigation.MainActivity" -e command login -e user "examplecustomer:exampledriver" -e tdetoken "tokendata" -e tokenexpiry "YYYY-MM- DThh:mm:ssZ" ""

Solicitud de Navigation:

Intent intent = getPackageManager().getLaunchIntentForPackage("com.telogis.nav6"); double latitude = 43.645238 double longitude = -79.364566 string hazmatSettings = "1,2,3" intent.PutExtra("command", "navigate");

// Especificación opcional de banner para un banner personalizado de parte superior o inferior (o ambas): int topBannerHeight = 50; int bottomBannerHeight = 50; intent.PutExtra("TopPadding", topBannerHeight);intent.PutExtra("BottomPadding", bottomBannerHeight);

// Datos de autenticación opcionales intent.PutExtra("user", "FleetName:Username"); intent.PutExtra("tdetoken", "Token"); intent.PutExtra("tokenexpiry", "YYYY-MM-DDThh:mm:ssZ");

// Fin de datos opcionales de autenticación intent.PutExtra("latitude", latitude); intent.PutExtra("longitude", longitude); intent.PutExtra("address", "Address"); intent.PutExtra("hazmat", hazmatSettings);intent.PutExtra("dimensionunits", "m"); intent.PutExtra("length", "27.4321"); intent.PutExtra("width", "2.5908"); intent.PutExtra("height", "4.1148"); intent.PutExtra("weightunit", "lb"); intent.PutExtra("grossweight", "79365");

// Ejecutar NavGE y transmitir parámetros de solicitud startActivity(launchIntent);

A través del Administrador de actividades de ADB (línea de comando Linux/MacOS):

adb shell am start -a android.intent.action.VIEW -n com.telogis.nav6/telogis.navigation.MainActivity --es command navigate --es latitude 43.651511 --es longitude -79.372205 --es hazmat 1,2,3 --es dimensionunits m --es length 27.4321 --es width 2.59082 --es height 4.11480 --es weightunit lb --es grossweight 79367

A través del Administrador de actividades de ADB (línea de comando Windows):

iOS

Registrar esquema de URL de NavGE en aplicación iOS:
NavGE proporciona un esquema de URL TelogisNavigationGlobal://. Una aplicación de iOS puede transmitir una cadena de consulta a NavGE al ejecutar NavGE.
Para comprobar si puede abrirse NavGE con el método canOpenURL, registre el esquema de la URL en info.plist de la aplicación iOS.
<key> LSApplicationQueriesSchemes</key> <array> <string> TelogisNavigationGlobal</string> </array>

Ejecutar NavGE y transmitir solicitud a NavGE con OpenUrl:
Solicitud de inicio de sesión:

string url = "TelogisNavigationGlobal://?" + "command=login" + "&user=FleetName:UserName" + "&tdetoken=Token" + "&tokenexpiry=TokenExpiry";

// Ejecutar NavGE y transmitir parámetros de la solicitud UIApplication.SharedApplication.OpenUrl(url);

Solicitud de Navigation:

// Escribir los datos del sitio en la mesa de trabajo si hay un sitio asociado con la ubicación. String SiteData = …; String siteKeyInPasteBoard = "site"; UIPasteboard.FromName pasteBoard = UIPasteboard.FromName(siteKey, true ); pasteBoard.String = SiteData;

string url = "TelogisNavigationGlobal://?" + "command=navigate" + "&latitude=Latitude" + "&longitude=Longitude" + "&address= Address" + "&site=" + siteKeyInPasteBoard // the name of the pasteboard of the site data. "&user=FleetName:UserName" + // optional, do not have to pass user credentials if the user has logged in previously. "&tdetoken=Token" + "&tokenexpiry=TokenExpiry" + "&hazmat=HazmatSettings" + "&dimensionunits=DimensionUnits" + "&length=Length" + "&width=Width" + "&height=Height" + "&weightunit=WeightUnit" + "&grossweight=GrossWeight" +

// Ejecutar NavGE y transmitir parámetros de la solicitud UIApplication.SharedApplication.OpenUrl(url);

Intenciones generales de Navigation en Android

En la plataforma Android, Navigation también recibe intenciones implícitas de otras aplicaciones. A continuación, se describen los esquemas de intenciones y el comportamiento de Navigation para cada uno de ellos.

NavGE admite el esquema de Geo y el esquema de Navigation.

Esquema de Geo

geo:latitude,longitude
Navega a la ubicación con la longitud y latitud proporcionadas.
Ejemplo: geo:43.780252,-79.411594

geo:latitude,longitude?z=zoom
Navega a la ubicación con la latitud y la longitud proporcionadas con un determinado nivel de zoom.
Ejemplo: geo:43.780252,-79.411594?z=11
Note: NavGE ignora z=zoom value.

geo:0,0?q=latitude,longitude(label)
Navega a la ubicación con la longitud y latitud proporcionadas con una etiqueta de cadena.
Ejemplo: geo:0,0?q=43.780252,-79.411594(Treasure)
Nota: NavGE intenta navegar con las coordenadas proporcionadas, pero se ignora la cadena de etiquetas.

geo:0,0?q=my+street+address
Navega a la ubicación "mi dirección" (puede ser una consulta de dirección o ubicación específicas).
Ejemplo: geo:0,0?q=20+Enterprise%2C+CA
Note: Todas las cadenas que se transmiten en la URI de Geo deben codificarse. Por ejemplo, la cadena “1st & Pike, Seattle” debería ser 1st%20%26%20Pike%2C%20Seattle. Los espacios en la cadena deben codificarse con un %20 o reemplazarse por el signo más (+).
Esquema de Google Navigation
Utilice esta intención para navegar a la dirección o coordenada específicas.
- google.navigation:q=a+street+address
- google.navigation:q=latitude,longitude
- google.navigation:ll=latitude,longitude

Casos de uso específicos

Direcciones comúnmente desconocidas para NavGE

Los usuarios que navegan a áreas recientemente desarrolladas con direcciones que no pueden codificarse de manera geográfica deberían utilizar una definición del sitio. Una definición de sitio debería incluir lo siguiente:

Coordenadas de latitud y longitud, ingresadas en los campos "lat" y "lon".
Información de la dirección, ingresada en el campo "nombre".

En el siguiente ejemplo, se muestra un comando de navegación y una definición de sitio:

command = navigate site = "{\"id\": 0,\"position\": {\"lat\": 54.980771,\"lon\": -1.646463} ,\"name\":\"Dirección o nombre que se le quiere mostrar al conductor\",\"addresses\": [ {\"city\": \"Nombre de ciudad para mostrar, si se quiere\"} ]}";

Este comando navega a la lat/lon proporcionadas. Valor de la clave "name" que se muestra en la parte superior de la pantalla Descripción general de la ubicación de la aplicación NavGE.