iOS URL Schemes

Custom URL schemes can be used in iOS to launch and send data to another application on the device. TMM registers several custom URL schemes with the operating system.

The URL schemes will activate TMM and bring it to the foreground.
The URL schemes will launch TMM if TMM is not already running.
The URL schemes may be used to show TMM user interfaces.
Some URL schemes query information from TMM, which will send the information via a return URL supplied by your application.

Passing Parameters

To pass paramaters between the your applicatoin and TMM:

Create a JSON object that maps parameter names and values. Encode it as a UTF-8 string. Example:
```
{param1:"value 1",param2:"value 2",param3:"value 3"}
```

Encode the UTF-8 string as Base64. Example:

e3BhcmFtMToidmFsdWUgMSIscGFyYW0yOiJ2YWx1ZSAyIixwYXJhbTM6InZhbHVlIDMifQ==

Append the Base64 string as the query portion of the URL. Example:

{scheme}://{authority}/{path}?e3BhcmFtMToidmFsdWUgMSIscGFyYW0yOiJ2YWx1ZSAyIixwYXJhbTM6InZhbHVlIDMifQ==

Return URL - Getting a response from TMM

Some TMM URL schemes pass a response back to your application, using your application’s custom URL scheme.

Register your URL scheme. You can do this in the XCode URL Types workflow, or you can add it to the info.plist file manually.
Handle incoming URLs in your app delegate.
For any TMM scheme that requires a returl, pass a URL that uses your custom URL scheme. Example:
```
{returl="my-custom-scheme://handle-tmm-response"}
```
TMM will then format the response to your request using returl. Example:
```
my-custom-scheme://handle-tmm-response?{base64-encoded-json-object}
```

For more information, see Defining a custom URL scheme for your app.

iOS URL Schemes

tmm — Ping the application

Remarks

This method is triggered by the tmm URL scheme. It initiates a ping to the TMM application to check its availability.

Inputs

Request URL

tmm://

Outputs

None

tmmconnect — Client application login

Remarks

Trimble Mobile Manager provides an URL interface so third party applications can log-in to Trimble ID (TID) via TMM. This allows an easy integration without going into implementation details of OAuth which is used in TID.

Inputs

Request URL

tmmconnect://?{base64-encoded-json-object}

application_id (string): The application ID.
returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

UserTID (String): The user’s TID.
DeviceID (String): The device ID.
TPSDKVersion (String): The TPSDK version.

tmmcorrectionsettings — Open the Configuration page.

Remarks

This method is triggered by the tmmcorrectionsettings URL scheme. Navigates TMM to the configuration page to edit the correction settings.

Inputs

Request URL

tmmcorrectionsettings://

Outputs

None

tmmfilelocations — Query file locations

Remarks

This method is triggered by the tmmfilelocations URL scheme. It retrieves the base location, correction settings path, and license report path from the platform details.

Inputs

Request URL

tmmfilelocations://?{base64-encoded-json-object}

returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

baseLocation (String): The base location for the operation.
correctionSettings (String): The settings for the correction process.
licenseReport (String): The report of the license status.

tmmlogin — Client application login

Remarks

Inputs

Request URL

tmmconnect://?{base64-encoded-json-object}

application_id (string): The application ID.
returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

UserTID (String): The user’s TID.
DeviceID (String): The device ID.
TPSDKVersion (String): The TPSDK version.

tmmondemand — Open to the On Demand page

Remarks

This method is triggered by the tmmondemand URL scheme. It retrieves the current claim and the remaining session time from the licensing container.

Inputs

Request URL

tmmondemand://?{base64-encoded-json-object}

application_id (string): The ID of the application.
returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

currentClaim (String): The current claim in the process.
claimCountdown (String): The countdown for the claim.

TmmOpenLaserOffset — Open the Laser Offset.

Remarks

This method is triggered by the TmmOpenLaserOffset URL scheme. Opens the Laser Offset data collection workflow in TMM.

Inputs

Request URL

TmmOpenLaserOffset://?{base64-encoded-json-object}

returl (string): The return URL TMM will open after completion of the Laser Offset workflow.

Outputs

Response URL

{returl}?referenceContext=addVertex&geometry={latitude},{longitude},{elevation}&useLocationProfile=true&useAntennaHeight=false&featureAttributes={featureAttributes}

Note: The response URL for TmmOpenLaserOffset is not typical of TMM-API iOS requests. Output parameters are URL encoded instead of a Base64 encoded JSON object.

referenceContext (string): addVertex
geometry (string): Comma-separated "{latitude},{longitude}" or "{latitude},{longitude},{elevation}" (elevation omitted if not available).
useLocationProfile (string): true
useAntennaHeight (string): false
featureAttributes (string): URL encoded JSON object. Compatible with ESRI GNSS / offset metadata fields.

TmmOpenToAntennaHeight — Open the Antenna Height page.

Remarks

This method is triggered by the TmmOpenToAntennaHeight URL scheme. Navigates TMM to the Antenna Height page.

Inputs

Request URL

TmmOpenToAntennaHeight://

Outputs

None

tmmopentoconfiguration — Open the Configuration page.

Remarks

This method is triggered by the tmmopentoconfiguration URL scheme. Navigates TMM to the Configuration page.

Inputs

Request URL

tmmopentoconfiguration://

Outputs

None

tmmopentologinpage — Open the login page

Remarks

This method is triggered by the tmmopentologinpage URL scheme. It initiates the process of navigating to the login page in the TMM application.

Inputs

Request URL

tmmopentologinpage://?{base64-encoded-json-object}

application_id (string): The ID of the application.
returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

tmmopentoreceiverselection — Open the receiver selection page

Remarks

This method is triggered by the tmmopentoreceiverselection URL scheme. Opens TMM to the receiver selection popup.

Inputs

Request URL

tmmopentoreceiverselection://

Outputs

None

TmmOpenToSkyplot — Open the Skyplot page.

Remarks

This method is triggered by the TmmOpenToSkyplot URL scheme. Navigates TMM to the Skyplot page.

Inputs

Request URL

TmmOpenToSkyplot://

Outputs

None

tmmpseudosecuresocketserver — Request to start the pseudo-secure socket server.

Remarks

This method is triggered by the tmmpseudosecuresocketserver URL scheme. It initiates the process of starting the pseudo-secure socket server in the TMM application.

Inputs

Request URL

tmmpseudosecuresocketserver://?{base64-encoded-json-object}

returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

port (Int): Legacy - The secure port for the V1 WebSocket
apiPort (Int): The insecure port number for the REST API
apiSecurePort (Int): The secure port number for the REST API
locationPort (Int): The insecure port for the V1 WebSocket
locationSecurePort (Int): The secure port for the V1 WebSocket
locationV2Port (Int): The insecure port for the V2 WebSocket
locationV2SecurePort (Int): The secure port for the V2 WebSocket

tmmrefreshusertoken — Refresh the user token.

Remarks

This method is triggered by the tmmrefreshusertoken URL scheme. It initiates the process of refreshing the user token in the TMM application.

Inputs

Request URL

tmmrefreshusertoken://?{base64-encoded-json-object}

application_id (string): The ID of the application requesting the user token refresh.
returl (string): The URL to which the application will return after the user token refresh process is complete.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

result (int): The result of the user token refresh operation.
- 0: “Refresh failed.”: Indicates that the user token refresh failed due to an unspecified error.
- 1: “No RefreshToken.”: Indicates that the user is not logged in and therefore no refresh token is available.
- 2: “Refresh not needed now.”: Indicates that the user token is already up-to-date and no refresh is necessary at this time.
- 3: “Refresh failed.”: Indicates that the user token refresh failed due to an expired refresh token.
- 4: “Refresh succeeded.”: Indicates that the user token refresh was successful.
message (String): Additional information or details about the result of the user token refresh operation.

tmmregister — Register client application

Remarks

This method is triggered by the tmmregister URL scheme. It retrieves the port information for the API server, LocalHost server, and LocalHost server V2. The port information includes the API port, location port, location secure port, and location V2 port.

Inputs

Request URL

tmmregister://?{base64-encoded-json-object}

application_id (string): The ID of the application requesting the socket server port information.
returl (string): The URL to which the application will return after the socket server port information is retrieved.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

registrationResult (String): Indicates the result of the registration check. This can be “OK”, “NoNetwork”, or “Unauthorized”
locationPort (Int): The insecure port for the V1 WebSocket
locationSecurePort (Int): The secure port for the V1 WebSocket
apiPort (Int): The insecure port number for the REST API
apiSecurePort (Int): The secure port number for the REST API
locationV2Port (Int): The insecure port for the V2 WebSocket
locationV2SecurePort (Int): The secure port for the V2 WebSocket

tmmsocketserverport — Query the list of TMM server ports

Remarks

This method is triggered by the tmmsocketserverport URL scheme. It retrieves the port information for the API server, LocalHost server, and LocalHost server V2. The port information includes the API port, location port, location secure port, and location V2 port.

Inputs

Request URL

tmmsocketserverport://?{base64-encoded-json-object}

returl (string): The return URL TMM will open after completion of this operation.

Outputs

Response URL

{returl}?{base64-encoded-json-object}

port (Int): Legacy - The insecure port for the V1 WebSocket
apiPort (Int): The insecure port number for the REST API
apiSecurePort (Int): The secure port number for the REST API
locationPort (Int): The insecure port for the V1 WebSocket
locationSecurePort (Int): The secure port for the V1 WebSocket
locationV2Port (Int): The insecure port for the V2 WebSocket
locationV2SecurePort (Int): The secure port for the V2 WebSocket