Considerations and Guidelines for Deep Link Setup

Deep Link Trigger Conditions

To trigger deep link events, make sure the app is running in the background with the corresponding user interface (UI) or process context open. For example, to integrate KPIs into the survey, the survey UI is open in the mobile app.

The CG Cloud mobile app restarts and the deep link events aren't processed when:

• You close the app.
• The app is killed in the background.
• You change the UI context or go to a different page in the app.

Payload URL Structure and Encoding Requirements

• The maximum size of an accepted Base64 encoded deep link URL is 400 KB. This size is calculated as the number of products in a survey x the number of KPIs (image recognition or survey response) per product.
  

  Tip The number of products can vary based on the incoming data structure. It's a good practice to optimize the data structure to send only the necessary data.

  Here's a sample of a lean JSON format to define KPIs for a product.

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

  This sample JSON uses an elaborate data structure with a verbose format containing unnecessary elements. We recommend that you collaborate with your vision partner to ensure that the incoming JSON data is optimized and contains only relevant KPIs.

  {
    "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//

• Always encode the payload by using Base64. Base64 encoding helps to support special characters and multi-byte characters in the URL without significantly increasing the payload size. This lets you include it as a URL query parameter in the deep link to the CG Cloud mobile app.
• For JavaScript BTOA function to work, your input text has to be a string with single-byte characters. For this, encode a JSON payload using Base64. To do so, first convert the JSON payload into a byte array. Then, convert the byte array to a string of single-byte characters. Finally, encode this string using Base64.

  This sample code creates a URL with a Base64-encoded payload that includes the name Alpine and the price 67.23.

  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}`;

  If the JSON data contains single-byte characters, then the external app can directly use Binary to ASCII (BTOA) for Base64 encoding.

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

• Irrespective of the programming language, make sure the third-party app that you use can convert the payload to JSON and then to a Base64 encoded string. You can replicate this process in Python, Swift Foundation, or Kotlin to produce the same encoded string.

Deep Link Modeling and Customization Considerations

• You can use only one linkLaunchEvent in a process flow.
• You can’t use eval functions in the business logic of your customization project. Deployment package in Visual Studio Code based Modeler can't be generated when an eval function is detected. Use safer alternatives to the eval function to build and deploy your customization.
• Deep link customization testing in Visual Studio Code based Modeler
  • You can’t invoke the deep link directly for web simulator in VS Code based Modeler. You can test customizations in contracts by registering events and configuring the business logic to handle it. Then invoke the window.handleOpenUrl function from Chrome's dev console.

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

  • When testing a deep link in Visual Studio Code-based Modeler, errors appear in the Chrome console log and the app logs page.

Data Storage and Sync Considerations

• To optimize storage and processing power and ensure adherence to Salesforce governor limits, store KPI snapshots in a data lake, such as Salesforce Data Cloud. Avoid storing the full KPI history directly in your Salesforce org. The mobile app can save a maximum of 300 data points or exceptions per visit.
• In your deep link custom project, configure the sync process to sync data after each visit. Use the Complete Call or Complete Cancel Call sync option in visit template. When there are many data uploads from multiple visits, the sync process becomes slower.

Security Considerations

Implement necessary security measures to ensure that only trusted sources access the deep links or under specific conditions.

Error handling

When a deep link processing error occurs, the linkLaunchEvent handler receives an error object containing an error code (MOBILE_LINK_ERROR_CODES) and a message. You can use these error codes in business logic to show appropriate localized error messages. You can view the error logs in the Device Events Log page in Sync Management.

ewoidmlzaXRJZCI6IDEwMiwKImtwaXMiOiBbCnsKInBy3RJZCI6IDEsCiJPdXRPZlN0b2NrIjogTm8sCiJTaGFyZU9mU2hlbGYiOiAzMCwKIkV5ZUxldmVsIjogQWJvdmUsCiJQT1NNRm91bmQiOiBObwpCl0=