On Device + Deep Linking

On Device Application and Deep Linking

On-Device Application Integration Services Overview

As some Trax customers use an SFA application and would like to benefit from Trax Image Recognition and Analysis capabilities, Trax offers a joint integration solution. The integration allows triggering Trax Mobile application within another application on the same device.

The link operates Trax standard API, using the context of a common store number combined with a unique session ID (both provided by Trax and by the calling application on each activation of the interface).

This context invokes a single store visit in the Trax Mobile application, and allows the user to select a task and to capture images in the store.

If a 'callback URL' is provided in the triggering request, Trax Mobile application will return the session resolution, providing the triggering application with information regarding the users's visit experience.

On-Device Application Integration Services Setup

The Trax application requires a named user to be logged-in in order to start a store visit. These users must be registered in Trax systems and granted permissions to use the Mobile application. If Trax Master Data API is used, this is done by invoking the Users API (V4 or V5).

When the application is launched for the first time, whether via linking or otherwise, a pre-login screen will appear, prompting the user to enter his email. After entering an email the configuration of the user will be checked and the login phase will continue in one of the following ways:

Triggering the Trax application within another application to START A VISIT or a start a task as part of an already started visit

You can pass parameters through deeplink in the below format:

com.traxretail.traxretail://startSession?{my_param}={some_value}&{my_param}={some_value}...

The following are the available parameters. Mandatory fields indicated by ＊

storeNumber*

Store Number as it appears in the Trax system. To start a visit for a store you need to pass the store number as the store identifier

clientSessionID*

The session id as it appears in the customer's system. When combined with the Trax session id it provides a link between the Trax and the customer data for a given session

callbackUrl

URI of your app that the user will be redirected when ending the visit

project

The project name of the store. Mainly used for customers who have multiple projects

username

The user name identifier for login to trax application. Mainly use when it's important to have permission per user to start a visit in the desired store

route

Route number as it appears in Trax. Mainly used if it's important to select the desired route per visit. If this value is Null, then the app will automatically select route

visitType

Visit type UID as it appears in Trax. Only relevant for customers with multiple visit types. If not provided, then the mobile user needs to select the desired visit type

taskNumber

Task ID (pk) as it appears in Trax, applicable for Capture task only. Tasks that have been duplicated by the user cannot be called. Mainly use when it's important to direct the end-user to a specific task

taskCallbackURL

URI of your app that the user will be redirected when completing/cancelling a task

Android - Java Example

private void deepLink(){

String yourCallbackURL = "com.app.foo";

String uri = "com.traxretail.traxretail://startSession?clientSessionID="+{escapedSessionID}+"&storeNumber="+{escapedStoreNumber}+"&callbackUrl"+{yourCallbackURL}"&project="+{projectName};

Intent intent = new Intent(Intent.ACTION_VIEW);

intent.setData(Uri.parse(uri));

startActivity(intent);

}

@IBAction func deepLink(sender: AnyObject) {

let application = UIApplication.sharedApplication()

let sessionID = NSUUID().UUIDString

let storeNumber = "9283742930"

let escapedSessionID = sessionID.stringByAddingPercentEncodingWithAllowedCharacters(.URLQueryAllowedCharacterSet())!

let escapedStoreNumber = storeNumber.stringByAddingPercentEncodingWithAllowedCharacters(.URLQueryAllowedCharacterSet())!

let yourCallbackURL = "com.app.foo"

let urlString = "com.traxretail.traxretail://startSession?clientSessionID=\(escapedSessionID)&storeNumber=\(escapedStoreNumber)&callbackUrl=\(yourCallbackURL)&project=\(projectName)"

guard let url = NSURL(string: urlString) else { return }

application.openURL(url)

}

iOS - Swift Example

HTML code Example

<a href="com.traxretail.traxretail://startSession?

clientSessionID={escapedSessionID}&

storeNumber={escapedStoreNumber}&

callbackUrl={yourCallbackURL}&

project={projectName}" >

Callback on visit level

If a callbackUrl is provided in the triggering request, Trax Mobile application will return a callback after ending or cancelling a visit with the session resolution in the following format:

{callbackUrl}://sessionEnded?{param}={value}&{param}={value}...

Parameters provided in the callback:

clientSessionID

If provided while starting a visit, the Trax app will return the same value. The value can be null

status

The status fo the visit can be one of the following fields. Please note it can not be null

"completed" (The 'Finish' button has been pressed by the user)
"canceled" (The session has been canceled by the user)
"canceledWithTasks" (The session has been canceled by the user after tasks were performed)
"endOfDay" (The session was left open by the user, trax closes it at the end of day, 12:00 AM)

// in AppDelegate

func application(_ app: UIApplication, open url: URL, options:[UIApplicationOpenURLOptionsKey : Any]) -> Bool {

// parse the url params here, for exampe for this url:

// "www.foo.com?a=\(1)&b=\(2)&c=3"

let queryItems = URLComponents(string: url)?.queryItems

let params:[[String: String?]]? = queryItems?.map({[$0.name: $0.value]})

print(params?) // will output [["a": "1"], ["b": "2"], ["c": "3"]]

}

iOS - Swift Callback Example

Android - Java Callback Example

private void handleDeepLink(Intent intent) {

String action = intent.getAction();

if (action.equals(Intent.ACTION_VIEW)){

Uri data = intent.getData();

if (data != null) {

UrlQuerySanitizer sanitizer = new UrlQuerySanitizer(data.toString());

String status = sanitizer.getValue("status");

String clientSessionUID = sanitizer.getValue("clientSessionID");

handleDeepLink(status, clientSessionUID);

}

For more info, please refer to Googles deeplink documentation:

https://developer.android.com/training/app-links/deep-linking.html

https://developer.android.com/training/app-links/index.html

Callback on the task level

If both a taskNumber and a taskCallbackURL are provided in the triggering request, Trax Mobile application will return a callback with the task resolution in the following format:

{taskCallbackURL}://taskEnded?{param}={value}&{param}={value}...

Parameters provided in the callback:

clientSessionID

taskNumber

status

The status fo the task can be one of the following fields. Please note it can not be null

"completed" (The 'Complete' button has been pressed by the user)
"canceled" (The task has been canceled by the user without image capturing, ie. tha BACK button has been pressed by the user.)
"canceledWithImages" (The task has been canceled by the user after capturing images, ie. the BACK button has been pressed by the user after taking images)

Triggering the Trax application within another application to END A VISIT

You can pass parameters through deeplink in the below format:

com.traxretail.traxretail://endSession?{my_param}={some_value}&{my_param}={some_value}...

The following are the available parameters. Mandatory fields indicated by ＊

clientSessionID*

The session id as it appears in the customer's system. When combined with the Trax session id it provides a link between the Trax and the customer data for a given session

callbackUrl

URI of your app that the user will be redirected when ending the visit

Please note, that

after triggering the Trax RE App to end a visit via deeplinking,
- the visit will be automatically ended only if all the requirements at Trax end for ending the visit are met (eg. all mandatory tasks are completed, no incomplete optional tasks are in the task list etc.) - otherwise the user will be navigated to the Trax RE App and asked to do the necessary actions and manually end the visit,
- similarly, the visit will not be ended automatically if there is an ongoing task, ie. a capture task which was previously started but not completed or cancelled by the user - in this case, the user is asked to complete the task and end the visit manually,
after ending the visit, the user will only be navigated back to the hosting app if the deeplink contains a callbackURL.

Callback on visit level

If a callbackUrl is provided in the triggering request, Trax Mobile application will return a callback after ending or cancelling a visit with the session resolution in the following format:

{callbackUrl}://sessionEnded?{param}={value}&{param}={value}...

Parameters provided in the callback:

clientSessionID

If provided while starting a visit, the Trax app will return the same value. The value can be null

status

The status fo the visit can be one of the following fields. Please note it can not be null

"completed" (The 'Finish' button has been pressed by the user)
"canceled" (The session has been canceled by the user)
"canceledWithTasks" (The session has been canceled by the user after tasks were performed)
"endOfDay" (The session was left open by the user, trax closes it at the end of day, 12:00 AM)