SharinPix Mobile App : Deeplink syntax

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

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

Note:

Links that launch the SharinPix Mobile App.

Some features 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 mode parameter will launch the SharinPix Mobile app on the specified mode by default.

The parameter mode takes these values: 

  • camera - this mode opens the camera when the SharinPix mobile app is launched. The mode option is set to camera by default.
  • roll - this mode opens the roll/gallery of the mobile device when the SharinPix mobile app is launched.
  • systemcam - this mode opens the system camera when the SharinPix mobile app is launched.
  • scan - this mode opens the document scanner when the SharinPix mobile app is launched.
  • snapsay - this mode opens the Snap & Say when the SharinPix mobile app is launched.
  • roomplan - this mode opens the roomplan mode directly when the SharinPix mobile app is launched.

Example: 

sharinpix://upload?token=.....&mode=roll

Visibility for the Modes

roll

The roll option allows you to choose photos from roll/gallery of the mobile device.

The parameter roll takes two values:

  • true  - When set to true, the roll option is kept in the list of modes available in the scrollable horizontal list when opening the SharinPix mobile app. The roll option is set to true by default.
  • false - Setting the value to false will remove the roll option from the scrollable horizontal list of modes on the camera view when launching the SharinPix mobile app.

Example: 

sharinpix://upload?token=.....&roll=false

systemcam

The systemcam option allows you to take photos from the system camera easily and conveniently.

The parameter systemcam takes two values:

  • true  - When set to true, the systemcam option is kept in the list of modes available in the scrollable horizontal list when opening the SharinPix mobile app. The systemcam option is set to true by default.
  • false - Setting the value to false will remove the systemcam option from the scrollable horizontal list of modes on the camera view when launching the SharinPix mobile app.

Example: 

sharinpix://upload?token=.....&systemcam=false

scan

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

The parameter scan takes two values:

  • true - When set to true, the scan option is kept in the list of modes available in the scrollable horizontal list when opening the SharinPix mobile app. The scan option is set to true 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.

Example: 

sharinpix://upload?token=.....&scan=false

Tips:

snapsay

The Snap & Say option allows you to snap photos easily, and instead of writing a description, you can use the voice recorder to record it. The recording will then be saved as the description of the image.

The parameter snapsay takes two values:

  • true  - When set to true, the snapsay option is kept in the list of modes available in the scrollable horizontal list when opening the SharinPix mobile app. The snapsay option is set to true by default.
  • false - Setting the value to false will remove the scapsay option from the scrollable horizontal list of modes on the camera view when launching the SharinPix mobile app.

Example: 

sharinpix://upload?token=.....&snapsay=false

roomplan

The roomplan mode allows you to create detailed 3D models of rooms and buildings for various applications, such as interior design and furniture placement. 

The parameter roomplan takes two values:

  • true - When set to true, the roomplan option is kept in the list of modes available in the scrollable horizontal list on the camera view. The roomplan option is set to true by default.
  • false - Setting the value to false will remove the roomplan option from the scrollable horizontal list of modes on the camera view when launching the SharinPix mobile app.

Example: 

sharinpix://upload?token=.....&roomplan=false

For more information about the RoomPlan feature, refer to the following article: SharinPix Mobile App: RoomPlan

Note: 

The RoomPlan feature is currently available only on devices with a LiDAR scanner, including: 

  • iPhone 12 Pro and later models
  • iPad Pro (3rd generation) and later models

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 enables a "slow mode" where, after each image is captured, a preview is displayed. This allows you to review, edit, or validate the images before proceeding with your next task. 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.

The checklist parameter can also be used alongside the checklist_ref parameter. The resulting list of tags will be a combination of the tags configured on the mobile app global configuration for the checklist_ref used and the tags specified for the checklist parameter.

Note:

The tags key for a checklist_ref on the mobile app global configuration can be omitted if the checklist parameter is used alongside the checklist_ref parameter.

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

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

checklist_ref

The checklist_ref  parameter will load a checklist configured on the mobile app global configuration. The loaded checklist will either be a checklist with form features if form fields are configured or a normal checklist otherwise.

Example:

sharinpix://upload?token=...&checklist_ref=building-inspection

checklist_order

The different sections on the checklist page are by default sorted with sections having no images at the top of the page and sections with images moving to the bottom of the page. The checklist_order parameter allows you to override this behavior. The order of the sections is preserved and it does not depend on whether the section contains images or not.

The example below demonstrates how to configure the checklist_order parameter to preserve the orders of the different sections:

sharinpix://upload?token=...&checklist=Before;After&checklist_order=preserve

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

Configure the checklist order parameter

enforce_min_count

If a checklist is submitted with less images than the minimum count specified for any tag, a warning message is displayed to the user. However, the user will still be able to proceed by confirming the submission. To override this behaviour and prevent the user from submitting the checklist, the enforce_min_count parameter can be used. Set the parameter to checklist.

Examples: 

  • With checklist parameter

sharinpix://upload?token=...&checklist=Before;After&enforce_min_count=checklist

  • With checklist_ref

sharinpix://upload?token=...&checklist_ref=building-inspection&enforce_min_count=checklist

checklist_reload

This parameter can be used when using a checklist with form features if checklist_order is not set to preserve. When filling form fields in a checklist with form features, the checklist is not automatically reordered when an item changes from incomplete to complete or from complete to incomplete. To reorder the checklist, the user needs to click a reorder button. To reorder the checklist automatically, set the checklist_reload parameter to auto. When set to auto the reload button is not displayed anymore.

Example:

sharinpix://upload?token=...&checklist_ref=building-inspection&checklist_reload=auto

The checklist_reload 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

form_<form-field-name>

This parameter can be used when using a checklist with form features. The purpose of this parameter is to pre-fill form field values when loading a checklist. For example, if a checklist has a form field named status, a form_status parameter can be used. The value for this parameter is a list of form field values separated by a ";".

Example:

Lets assume that the building-inspection checklist_ref has 3 tags.

  • Link 1: sharinpix://upload?token=...&checklist_ref=building-inspection&form_status=OK;KO;NA 

    For link 1, the status form field for the first tag will have a value of OK, the second will be KO and the third will be NA. 

  • Link2: sharinpix://upload?token=...&checklist_ref=building-inspection&form_status=OK;KO

    For link 2, the status form field for the first tag will have a value of OK, the second will be KO and the third will have a default value or a value previously filled. 

  • Link 3: sharinpix://upload?token=...&checklist_ref=building-inspection&form_status=OK;;NA

    For link 3, the status form field for the first tag will have a value of OK, the second will unfilled and the third will be NA. 

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.
  • To configure the team checklist token abilities, you can either:
    • Create a SharinPix Permission with all required team checklist abilities and assign it to your component as explained here (admin-friendly method).
    • Programmatically configure the token as demonstrated in the code snippet available in this article if you are using a custom component (developer-oriented method). Note: For some custom components, you can directly pass a SharinPix Permission ID to provide the correct Team Checklist token abilities.

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_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

required

The required parameter allows a user to set a field as mandatory on a media record from the SharinPix mobile app. For example, the title  field can be required on the each image taken on the SharinPix mobile app. The following URL syntax shows how to set the title field as mandatory.

sharinpix://upload?token=<valuetoken>&required=title

More than one field can be set as required on an image, we can have both title field and description field as required. To set more than one field, the values need to be separated by the semicolon symbol  ";". See the following URL syntax.

sharinpix://upload?token=<valuetoken>&required=title;description 

The parameter required accepts the following values:

  • title
  • description

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. 

    Note: The spMediaCount stores the number of media files captured, not the number of uploads completed. The files still need to be uploaded to appear online. In exceptional cases where the user uninstalled the SharinPix app before uploads are complete, this count will not equal the number of uploads completed.

  • 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 or when submitting a checklist with form features. The app will not automatically exit until the uploads are complete.

This parameter takes two values:

  • batch: Used to show the image upload progress and wait for completion before exiting when submitting a batch
  • checklist: Used to show the image upload progress and wait for completion before exiting when submitting a checklist with form features

Example:

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 unit value, you need to encode the unit 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/

template_image

The template_image parameter takes as value a template image URL. This parameter allows users to open the template image in an annotation mode in the SharinPix mobile app.

The following example demonstrates how to make use of a deeplink to launch the SharinPix app in annotation mode:

template_image=https%3A%2F%2Fimage.test.com%2Fsmart_solar.png

Note:

The template image must be encoded upon configuration.

A convenient tool for this purpose is available at https://www.urlencoder.org/.

lens

The lens parameter allows you to specify the camera mode to be used when opening the camera. It takes two values:

  • auto: Opens the default camera
  • wide: Opens the wide camera

The following example demonstrates how to make use of a deeplink to open the wide camera directly in the SharinPix application:
 sharinpix://upload?token=...&lens=wide

Note:

Note that not all devices have wide-angle cameras. On some devices, access to wide-angle cameras is restricted to system applications only.

ocr

The ocr option allows text extraction while scanning documents or paperwork using the scan mode.

The parameter ocr takes two values:

  • true  - When set to true, the text recognition will be enabled on scan mode.
  • false - The ocr option is set to false by default, where no text will be extracted when scanning a document.

Example:

sharinpix://upload?token=.....&ocr=true

Note:

Note that the extracted text is saved in a SharinPix Image record. For more information on how to use OCR in scan mode, please refer to the following article: SharinPix Mobile App: Text Recognition on Scan (OCR)

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.