Deep Linking: Add Custom Values for Reporting and a Call Back URL

Custom Values for Reporting

The Custom Parameter deep link format provides an option for additional metadata (as defined by the company) to be associated to a Mission Response. The associated metadata can then be used in reporting, either through FORM's Advanced Insights offering or by using the GoSpotCheck External API.

This deep link structure will auto-start a Mission Response for the user. Once the Mission Response is completed, any metadata from the same deep link will be stored in the GoSpotCheck database and be available for reporting.

Examples of metadata that can be sent:

• Internal ids for users, places, etc.
• Regional information
• Other data as it pertains to your business

Call Back URL

Often times, a user will be deep linked into the GoSpotCheck app from an external application. They have to change apps manually after Mission Response submission.

Adding a Call Back URL to the deep link allows the user to automatically be redirected to a specified URL after Mission Response submission or cancellation. You do not need to add Custom Parameters to use a Call Back URL.

In addition, you can request certain GoSpotCheck data when the Call Back is made. This data could include:

• GoSpotCheck User or Place ID
• Status of the mission

Deep Link Structure

Inbound with Custom Parameters

gospotcheck://companies/{id}/missions/{id}/places/{id}/mission_responses/?start=true&customer_data={"visit_id":"value","task_id":"value"}&completion_trigger={"action_type":"url_redirect","value":"salesforce1://","mx_options":["status","mx_user_id"]}

Fields in orange are required as the bare minimum to generate a deeplink that will open the specified mission in the MX app and auto-start a mission response for the user.

Fields in blue are not required to generate the deeplink. However, they are required as written if the customer want to append custom data to the related mission response and / or wants to include a Callback URL on mission completion. 

Fields in green are supplied by the customer and customer defined.

Requirements

• Device is on iOS 15+ or Android OS 12+
• URL endcoding is required for query parameters
  • Note: URLs have a max 1500 character limit
• Customers can send up to 15 custom data keys (customer_data) to be stored in the MX database
  • If customers more than 15 custom data keys, FORM can’t guarantee the 16th plus key and associated values will be stored in the system
• A mission must be completed for this data to make it to the GoSpotCheck database and be reported on
  • i.e., a started and abandoned mission will not have this data in the GoSpotCheck database
• If a customer wants to send custom data associated to a specific mission response, the /mission_responses/?start=true parameter must be included in the deeplink. This parameter will auto start a Mission Response and is required to use the custom parameter feature. If it is not included, any additional parameters are ignored
• Duplicate parameter keys (i..e, customer_data) cannot be sent
• If customers do not want to include any customer_data, they can exclude that key from the URL
• If customers do not want to include a completion_trigger, they can exclude that key from the URL
• If customers include an mx_option that is not recognized by MarketX, it will be ignored

Additional Information

• Company ID will always be static content
• Place ID is the GoSpotCheck ID for place
• If deep linking from SalesForce, SalesForce can set a record variable to null in the javascript, causing anundefined\viewto be appended to the URL. The appendment will render the deep link invalid. The record variable must be updated for the deeplink to function as expected

Call Back Link Structure

Outbound with Custom Parameters

salesforce1://?customer_data={"visit_id":"value","task_id":"value"}&mx_options={"status":"value","gsc_user_id":"value"}

Fields in orange are the bare minimum required for the "completion_trigger" to function. This value is provided by the customer in the original inbound deep link (see above section on Inbound Deep Link Structure for more information).

Fields in blue will only be included in the call back link if they were provided by the customer in the original inbound deep link (see above section on Inbound Deep Link Structure for more information).

Additional Information

mx_options

• "mx_options" are keys that correspond to MarketX data that is available immediately from the mobile application on mission submission
• Customers can request any or none of the "mx_options" keys to be returned in the call back URL
  • Keys available are:
    • "status"
      • Customers will likely want to know the status of a Mission Response on the callback. The status field can be helpful in triggering further business operations within a customer’s other business systems
      • This value will come from the mobile application’s local storage and does not relate to the Web database
      • There are two statuses that MX will provide: "completed" and "cancelled"
        • "completed" means the mission was finished by the user and will be uploaded to the MX DB as soon as connectivity is sufficient for data transfer. Admins can expect to see the Mission Response through the Web Admin portal and / or API within 24 hours.
          • As an example, if a mission shows “pending approval” in the mobile application, the status will come back as completed in the call back URL
        • "cancelled" means the user did not finish the mission. Instead of submitting the mission, they select the “Cancel” button. Any data sent in the original deeplink URL, as well as any data associated with the uncompleted mission response, are deleted and not stored, even locally on the device
    • "mx_user_id"