SharinPix Mobile App : Deeplink syntax

SharinPix uses deeplink to launch the SharinPix mobile app from other apps including Salesforce mobile app, Field Service Lightning app or any of your app.

Our deeplink URL starts with sharinpix:// in place of http:// and opens our mobile app when installed properly on the device system.

There are some features that work with URLs but not with the Deeplink URL, such as URL Buttons in Salesforce. You may then have an error like can't reach the server.

Syntax

The general form of the deeplink URL is:

sharinpix://<verb>?<parameter1>=<value1>&<parameter2>=<value2>&....


The URL support two verbs:

Upload : to run the SharinPix Mobile App in order to take/choose pictures to upload

View : to run the SharinPix Mobile App in order to access to images already taken on that device

Upload

To upload images, you should use upload as a verb.

In that case the URL will have the following syntax:

sharinpix://upload?token=<valuetoken>&<parameter1>=<value1>&<parameter2>=<value2>&....

The token provides SharinPix with the target of the upload. You can read here to learn more about how to generate a token via Flow or Apex code.

This section lists the different parameters that can be used in the Deeplink URL.

mode

The parameter mode takes two values: 

  • camera - this mode opens the camera once the application is launched.
  • roll - this mode opens the roll/gallery of the mobile device once the application is launched.

roll

The parameter roll takes two values:

  • true  - this value allows the user to choose photos from the roll/gallery of the mobile device.
  • false - this value DOES NOT allow the user to choose from the roll/gallery of the mobile device.

confirmation

The parameter confirmation takes two values:

  • true -  this value previews the image on the display before uploading it.
  • false - this value DOES NOT preview an image on the display before uploading it.

confirm

The confirm parameter can also be configured at the organization level. For more information on how to perform this configuration, refer to the following article:

Mobile App Global Configuration

The confirm parameter is used to request confirmation from the user before the actual submission. A screen is shown with details of media to be submitted and the user can modify his input before finalizing the submission. This is added to the deeplink URL like: sharinpix://upload?token=...&confirm=batch.

tags

The tags  parameter takes a label as value(s) which will be then made available for selection in a menu. The user can then access the tag(s) from the menu to tag an image when using the SharinPix Mobile App URL Launcher. This tagging action is also available when clicking on a thumbnail.

  • The values are separated by the semicolon symbol “;”. 
  • If tags takes only one value, the semicolon can be omitted.
  • The figure below illustrates the result while accessing the Select Tags feature inside the SharinPix App.

Note: 

Spaces in tags values should be replaced by the %20 characters as demonstrated below:

sharinpix://upload?token=...&tags=Fisrt%20Tag

auto_tags

The auto_tags parameter takes as value(s) a label that will be automatically assigned to all images in the SharinPix Album when the SharinPix Mobile App URL Launcher is used.

  • The values are separated by semicolon symbol “;”. 
  • If auto_tags takes only one value, the semicolon can be omitted.

Note: 

Spaces in auto_tags values should be replaced by the %20 characters as demonstrated below:

sharinpix://upload?token=...&auto_tags=Fisrt%20Tag

default_tags

As depicted in the above figure, the tag Back is selected by default.

Characteristics of parameter default_tags:

  • Tags are selected by default.
  • More than one tag can be selected by default.
  • Tags can be selected/deselected by the user.

The default_tags parameter takes as value(s) a label that will be selected by default when the SharinPix URL Launcher is used.

  • The values are separated by semicolon symbol “;”. 
  • If default_tags takes only one value, the semicolon can be omitted.
  • The figure below illustrates the result obtained inside the SharinPix App when using the default_tags parameters in the Deeplink URL.

IMPORTANT:  If tag values contain special characters (i.e characters that are not on this list: https://www.w3schools.com/charsets/ref_html_ascii.asp), you need to URL Encode those special characters. URL encoding means converting special characters into a format that can be transmitted over the Internet.

EXAMPLE: If you want to use "éssai" as a tag value, you need to URL encode it first as it contains the special character, "é". There is a handy tool that can be used to perform this: https://www.urlencoder.org/ .

Note:

The semicolon symbol ";" is to be used to separate the tag values.

Note: 

Spaces in default_tags values should be replaced by the %20 characters as demonstrated below:

sharinpix://upload?token=...&default_tags=Fisrt%20Tag

checklist

The checklist option provides a list of tags ready to be filled with pictures. If a tag is associated with at least one picture, the associated tag turns from red to green. 

The checklist parameter takes a label as value(s) which represents all the tags that need to be filled with images.

  • The values are separated by the semicolon symbol “;”.
  • If the checklist is launched on a job for which some images have been provided already, the corresponding tags should reflect the existing images.

You will find more information about the different checklist configurations available in the following article:

http://docs.sharinpix.com/m/documentation/l/1126826-checklist

team

The team parameter allows the user to view images already uploaded to the album the checklist relates to. This includes images uploaded live to the same record and checklists by other users.

The parameter team can be:

  • true - Setting the value to true will allow the user to see the online images on the checklist page.
  • false (default) - Setting the value to false will show only the images present locally on the device.

sharinpix://upload?token=<SharinPix Token>&team=true

Tips

To retrieve the images you should make sure your token has at least the abilities: "see", "image_list" and "tags>read".

The necessary ability is required in the token so that it can access those tag images in the album.

flash

The parameter flash takes two values:

  • true  - this value forces the flash to be on
  • false - this value forces the flash to be off

Without values, the flash is not available. You may use  the Native Camera App access (long click on the shoot button) if you want to modify the flash options from the UI.


scan

The scan option allows you to snap/scan documents/paperwork easily and conveniently.

The parameter scan takes two values:

  • true - Setting the value to true will automatically open the SharinPix mobile app with the scan mode selected by default.
  • false - Setting the value to false will remove the scan option from the scrollable horizontal list of modes on the camera view when launching the SharinPix mobile app.

You will discover more about the scan option by clicking on the following URL:

http://docs.sharinpix.com/m/documentation/l/890613-smart-document-scanning 

scan_as

The scan_as option allows you to save the output for the scan files as images or pdf. As the default behaviour, one scan will be saved as an image and multiple scans will be saved as a pdf.

The parameter scan_as takes two values:

  • image - Setting the value to image will save the scan files as images on the SharinPix mobile app.
  • pdf - Setting the value to pdf will save the scan files as images on the SharinPix mobile app.

The scan_as parameter can also be configured at the organization level. For more information on how to perform this configuration, refer to the following article:

Mobile App Global Configuration

manual_jobs

The parameter manual_jobs permits the removal or addition of the + button from the SharinPix interface to give the ability (or remove the ability) to create jobs not yet related to a Salesforce record.

Using this with the value "false" will remove any access to the + button which permits the creation of jobs for all future usages.

Using this with the value "true" will give back the button for all the future usages.

skip_job_assoc

The SharinPix mobile App permits to create manual jobs and associate them after creation.

In that case, you are prompted to reconnect a job created manually when it is detected.

To avoid the job association detection, you can use the skip_job_assoc parameter.

The parameter skip_job_assoc takes two values:

  • true  - the job association screen is never displayed.
  • false - the job association screen is displayed each time a manual created job is detected.

ret_url

The ret_url parameter takes as value a return URL. This parameter allows users to return to external apps such as Salesforce mobile app or Salesforce Field Service app or any website URL once images are submitted via the SharinPix app. 

The following example demonstrates how to make use of a deeplink to launch the SharinPix app, then return to a specific record within the Salesforce app once are submitted:

sharinpix://upload?token=<valuetoken>&ret_url=salesforce1://sObject/<recordID>/view

Tip:

For more information about the Salesforce mobile app URL schemes refer to the following article:

Salesforce Mobile App URL Schemes

SharinPix also includes some additional parameters that can be used along with the ret_url. These parameters are:

  • spMediaCount: which returns the number of images captured
  • spBatchState: which provides details on the state. The values available for this parameter are SUBMITTED, UPLOADING and UPLOADED
  • spBatchId: which returns the batch ID
  • spAlbumId: which returns the album ID
  • spChecklistState: states whether the checklist has been completed or not. Values will be either OK or KO.
  • spCompletedTaskCount: which returns the number of tasks completed in the checklist.
  • spIncompleteTaskCount: which returns the number of tasks left incomplete in the checklist.

spChecklistState, spCompletedTaskCount and spIncompleteTaskCount will only be filled if the SharinPix app was opened in checklist mode; spMediaCount, spBatchState and spBatchId will not be filled in checklist mode.

The following example demonstrates how to make use of the above parameters in a decoded return URL for the SFS app (without newlines or spaces):

com.salesforce.fieldservice://v1/sObject/spAlbumId/flow/TakeSurvey?imgCount=spMediaCount&state=spBatchState&batchId=spBatchId&albumId=spAlbumId

Note:

The return URL should be encoded when configured for the SFS mobile app. Here is an example of an encoded return URL (without newlines or spaces):

com.salesforce.fieldservice%3A%2F%2Fv1%2FsObject%2FspAlbumId%2Fflow%2FTakeSurvey

%3FimgCount%3DspMediaCount%26state%3DspBatchState%26batchId%3DspBatchId%26alb

umId%3DspAlbumId

For more information on how to configure the ret_url for usage within the SFS mobile app, refer to the following article:

Using deeplink to return to SFS (FSL) Flow with additional image information

await_upload

The await_upload parameter can be used to show the upload progress after submitting images captured using the SharinPix mobile app. The app will not automatically exit until the uploads are complete.

This parameter takes two values:

  • true: Used to show the image upload progress and wait for completion before exiting
  • false: Default behaviour - uploads will be done in the background

The following example depicts the image upload progress when the await_upload parameter is set to true:

The await_upload parameter can also be configured at the organization level. For more information on how to perform this configuration, refer to the following article:

Mobile App Global Configuration

overlay

Use the overlay parameter with an image's URL to appear as an overlay image on top of the camera view. This can be handy if you need a guide to find the appropriate position and proportion.

sharinpix://upload?token=...&overlay=https%3A%2F%2FimageURL.jpg

overlay_opacity

Control the level of opacity of the overlay image with the overlay_opacity parameter. The value should be a number between 0 and 1. The default value is 0.5.

sharinpix://upload?token=...&overlay=https%3A%2F%2FimageURL.jpg&overlay_opacity=0.2

The confirm parameter can also be configured at the organization level. For more information on how to perform this configuration, refer to the following article:

Mobile App Global Configuration

watermark

The watermark parameter is used to set up and display watermarks on images captured from the SharinPix mobile app. This is added to the deeplink URL like: sharinpix://upload?token=...&watermark=SharinPixImage.

Note: Spaces in watermark values should be replaced by the %20 characters as demonstrated below:

sharinpix://upload?token=...&watermark=Hello%20World

The watermark parameter can be configured so as to also display the date/time and location at which the image was captured. The example below demonstrates how a decoded watermark value looks like:

Job-1 taken at <TIMESTAMP><LF>Location: <LAT>, <LON>

The above example returns a text similar to the one below on the image:

Job-1 taken at 2022-07-01 12:14:43 +0400

Location: 21.0000904, 23.4080982


The date/time and location can be configured using the following syntax:

  • <TIMESTAMP> : Returns the datetime in the format yyyy-MM-dd HH:mm:ss Z
  • <LF> :  Referring to Line Feed and used to add a new line.
  • <LAT> : Returns the latitude.
  • <LON> : Returns the longitude.


The watermark values should be encoded when configured in SharinPix deeplinks. Here is an example of an encoded watermark value in a SharinPix deeplink:

sharinpix://upload?token=...&watermark=Job-1%20taken%20at%20%3CTIMESTAMP%3E%3CLF%3ELocation%3A%20%3CLAT%3E%2C%20%3CLON%3E


Note: The decoded value of the above is: Job-1 taken at <TIMESTAMP><LF>Location: <LAT>, <LON>

Tip:

In the above encoded example, the spaces in watermark value are replaced by %20 characters and the opening (<) and closing (>) angle brackets are replaced by %3C and %3E characters respectively.

There is a handy tool that can be used to perform this: https://www.urlencoder.org/ .

The example below depicts a photo captured by the SharinPix mobile app with the following deeplink:

sharinpix://upload?token=...&watermark=Job-12%20taken%20at%20%3CTIMESTAMP%3E%3CLF%3ELocation%3A%20%3CLAT%3E%2C%20%3CLON%3E

In the above example:

  • The <TIMESTAMP> returned the date/time 2022-07-03 22:17:13-0400.
  • The <LAT> returned the latitude 43.6699136.
  • The <LON> returned the longitude -79.3903104.

The watermark parameter can also be configured at the organization level. For more information on how to perform this configuration, refer to the following article:

Mobile App Global Configuration

compass

The compass parameter is used to display a compass on the SharinPix mobile app's capture screen. 

This is added to the deeplink URL like: sharinpix://upload?token=...&compass=true

Tip:

  • On top of the true value, the compass parameter can also be activated using the on value, for example: sharinpix://upload?token=...&compass=on
  • To disable the compass parameter, simply remove the parameter from the deeplink or use the value false or off, for example: sharinpix://upload?token=...&compass=false

target_size

The target_size parameter allows you to set the resolution, in pixels, of the images captured with the app. For example, if you configure target_size to be 1024 pixels, the app will try to capture images with a width or height closer to 1024 pixels. In portrait orientation, the height of the image will be closer to 1024, while in landscape mode, it will be the width.

It is up to the mobile operating system to choose the closest supported resolution. 


iOS will choose the highest resolution from the following ordered list that is lower or equal to the target_size specified:

  • 3840 x 2160 (>= 3840)
  • 1920 x 1080 (>= 1920) Example target_size to use this 1920 x 1080: 2000
  • 1280 x 720 (>= 1280) Example target_size to use 1280 x 720: 1500
  • 640 x 480 (>= 640)
  • 352 x 288 (>= 352)


Unlike iOS, different Android phones have different possible resolutions that can be used to capture images. It is up to the system to choose the resolution closest to the target_size specified. In some cases, it may be higher than the target_size specified.


The example below demonstrates how to configure the target_size parameter to be 1920 pixels wide:

target_size=1920
Click to copy

As mentioned, target_size only applies to images taken with the SharinPix mobile app's camera. As such, images selected from the roll or taken with the system camera will not be resized.

units

The units parameter provides a list of units that can be used to annotate images on the SharinPix mobile app. The units are available in the dropdown, as depicted in the screen capture below, during the numerical annotation.

The units parameter takes a value(s) available in the dropdown list.

  • The values are separated by the semicolon symbol “;”.
  • If the units parameter includes one value, the semicolon can be omitted.

IMPORTANT:  

If the units parameter contains values with special characters (i.e characters that are not on this list: https://www.w3schools.com/charsets/ref_html_ascii.asp), you need to encode these special characters in the URL to convert the special characters into a format that can be transmitted over the Internet.

EXAMPLE: 

If you want to use "éssai" as a tag value, you need to encode the tag first in the URL as it contains the special character, "é". Here's a handy tool that can be used to encode URLs: https://www.urlencoder.org/

view_album

To view images taken on that device and not deleted yet, you should use view_album as the verb.

In that case the URL will be as follows:

sharinpix://view_album?album_id=<recordID>

album_id

The parameter album_id permits to choose the SharinPix Album to be displayed when launching the SharinPix mobile App.

  • The AlbumID represents the record ID on which the album is hosted. It should be expressed in the 18 digits version.
  • If used in a formula, you should use CASESAFEID function to assume this value is 18 digit version.
  • If pictures was taken on another device the view_album will not show the pictures.
  • If pictures was taken since a too long time view_album will not show any pictures.

online

To access online features such as SharinPix images, albums and search within the SharinPix mobile app itself, you should use online as a verb.

In such cases, the URL will be as follows:

sharinpix://online?token=<SharinPix Token>

The token can take various types of SharinPix tokens as values such as a token allowing access to:

  • A specific SharinPix album
  • Access to a specific SharinPix image for viewing or annotation or 
  • Access to a SharinPix Search

For more details on the online mode feature and how to generate tokens for the above functionalities, refer to the following article:

SharinPix Mobile App: Online mode

Note:

The SharinPix Online mode works only when there's an active internet connection.

1 Comments

lexie green

Thanks for sharing such valuable content. Comparing to urlencoder.org, there is another great tool https://url-decode.com/. URL-decode has 100+ web utilities for the users. To provide more value, to the users.

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.