Consideraciones y directrices para la configuración de vínculos profundos

Condiciones de desencadenador de vínculo profundo

Para desencadenar eventos de vínculos profundos, asegúrese de que la aplicación se ejecuta en segundo plano con la interfaz de usuario (UI) o el contexto de proceso correspondientes abiertos. Por ejemplo, para integrar indicadores clave de desempeño en la encuesta, la interfaz de usuario de la encuesta está abierta en la aplicación móvil.

La aplicación móvil CG Cloud se reinicia y los eventos de vínculo profundo no se procesan cuando:

• Cierra la aplicación.
• La aplicación se elimina en segundo plano.
• Cambia el contexto de la interfaz de usuario o se dirige a una página diferente en la aplicación.

Estructura de URL de carga y requisitos de codificación

• El tamaño máximo de una URL de vínculo profundo codificada con Base64 aceptada es de 400 KB. Este tamaño se calcula como el número de productos en una encuesta x el número de indicadores clave de desempeño (reconocimiento de imagen o respuesta de encuesta) por producto.
  

  Sugerencia El número de productos puede variar basándose en la estructura de datos entrante. Es una buena práctica optimizar la estructura de datos para enviar solo los datos necesarios.

  A continuación se incluye una muestra de un formato JSON Lean para definir los indicadores clave de desempeño para un producto.

  {
  "visitId": 102,
  "kpis": [
  {
  "productId": 1,
  "OutOfStock": No,
  "ShareOfShelf": 30,
  "EyeLevel": Above,
  "POSMFound": No,
  },
  …
  }

  Este JSON de muestra utiliza una estructura de datos elaborada con un formato verboso que contiene elementos innecesarios. Recomendamos que colabore con su socio de visión para garantizar que los datos JSON entrantes están optimizados y contienen solo KPI relevantes.

  {
    "storeId": "STORE_789",
    "visitId": "VISIT_GHI",
    "timestamp": "2025-05-07T11:52:00+05:30",
    "scanType": "PRODUCT_LEVEL_KPI_ARRAY",
    "productKpis": [
      {
        "productId": "PROD_JKL_500G",
        "sku": "SKU_1234",
        "kpis": [
          {
            "kpiName": "shelfAvailability",
            "value": 1.00,
            "unit": "boolean",
            "description": "Indicates if the product was found on the shelf"
          },
          {
            "kpiName": "facingCountActual",
            "value": 5,
            "unit": "count",
            "description": "Number of facings of this product detected"
          },
  //details omitted for brevity//

• Codifique siempre la carga utilizando Base64. La codificación Base64 ayuda a admitir caracteres especiales y caracteres de múltiples bytes en la URL sin aumentar significativamente el tamaño de la carga. Esto le permite incluirlo como un parámetro de consulta de URL en el vínculo profundo a la aplicación móvil CG Cloud.
• Para que la función BTOA de JavaScript funcione, su texto de entrada debe ser una cadena con caracteres de un solo byte. Para esto, codifique una carga JSON utilizando Base64. Para ello, convierta primero la carga JSON en una matriz de bytes. A continuación, convierta la matriz de bytes en una cadena de caracteres de un solo byte. Finalmente, codifique esta cadena utilizando Base64.

  Este código de muestra crea una URL con una carga codificada con Base64 que incluye el nombre Alpine y el 67.23 de precios.

  const payload = { name: 'Alpine', price: 67.23 };
  const encodedPayload = btoa(Array.from(new TextEncoder().encode(JSON.stringify(payload)), (byte) => String.fromCodePoint(byte)).join(""));
  const url = `cgcloud://share?payload=${encodedPayload}`;

  Si los datos JSON contienen caracteres de un solo byte, la aplicación externa puede utilizar directamente Binary to ASCII (BTOA) para la codificación Base64.

  btoa(JSON.stringify({name: 'Apline', price: 67.23}))

• Independientemente del lenguaje de programación, asegúrese de que la aplicación externa que utiliza puede convertir la carga en JSON y luego en una cadena codificada Base64. Puede replicar este proceso en Python, Swift Foundation o Kotlin para producir la misma cadena codificada.

Consideraciones de personalización y modelado de vínculos profundos

• Solo puede utilizar un linkLaunchEvent en un flujo de proceso.
• No puede utilizar funciones de eval en la lógica de negocio de su proyecto de personalización. El paquete de implementación en Modeler basado en Visual Studio Code no se puede generar cuando se detecta una función de eval. Utilice alternativas más seguras a la función eval para crear e implementar su personalización.
• Pruebas de personalización de vínculos profundos en Modeler basado en Visual Studio Code
  • No puede invocar el vínculo profundo directamente para simulador web en Modeler basado en VS Code. Puede probar personalizaciones en contratos registrando eventos y configurando la lógica de negocio para gestionarla. Luego invoque la función window.handleOpenUrl desde la consola de desarrollo de Chrome.

     window.handleOpenURL("cgcloud://share?payload=data")

  • Al probar un vínculo profundo en Visual Studio Code Modeler, aparecen errores en el registro de la consola Chrome y la página de registros de la aplicación.

Consideraciones sobre almacenamiento y sincronización de datos

• Para optimizar el almacenamiento y el poder de procesamiento y garantizar el cumplimiento de los límites reguladores de Salesforce, almacene instantáneas de KPI en un lago de datos, como Salesforce Data Cloud. Evite almacenar el historial de KPI completo directamente en su organización de Salesforce. La aplicación móvil puede guardar un máximo de 300 puntos de datos o excepciones por visita.
• En su proyecto personalizado de vínculo profundo, configure el proceso de sincronización para sincronizar datos después de cada visita. Utilice la opción Completar llamada o Completar sincronización de cancelación de llamada en plantilla de visita. Cuando hay muchas cargas de datos desde múltiples visitas, el proceso de sincronización se vuelve más lento.

Consideraciones de seguridad

Implemente las medidas de seguridad necesarias para garantizar que solo los orígenes de confianza acceden a los vínculos profundos o bajo condiciones específicas.

Gestión de errores

Cuando se produce un error de procesamiento de vínculo profundo, el controlador de linkLaunchEvent recibe un objeto de error que contiene un código de error (MOBILE_LINK_ERROR_CODES) y un mensaje. Puede utilizar estos códigos de error en lógica de negocio para mostrar mensajes de error traducidos apropiados. Puede ver los registros de errores en la página Registro de eventos de dispositivo en Gestión de sincronización.

ewoidmlzaXRJZCI6IDEwMiwKImtwaXMiOiBbCnsKInBy3RJZCI6IDEsCiJPdXRPZlN0b2NrIjogTm8sCiJTaGFyZU9mU2hlbGYiOiAzMCwKIkV5ZUxldmVsIjogQWJvdmUsCiJQT1NNRm91bmQiOiBObwpCl0=