Using iOS URL Schemes

View iOS URL Schemes Reference View the iOS URL schemes reference.

View TMM API Sample Code Sample code for TMM-API integrations is available on GitHub, including projects for Android, iOS and .NET MAUI.

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:

1. 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"}

2. Encode the UTF-8 string as Base64. Example:

   e3BhcmFtMToidmFsdWUgMSIscGFyYW0yOiJ2YWx1ZSAyIixwYXJhbTM6InZhbHVlIDMifQ==

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

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

Return URL

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

1. 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.
2. Handle incoming URLs in your app delegate.
3. 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"}

4. 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.

Example: Client Application Registration

Use the tmmregister URL scheme to register your client app with TMM.

Send the Request

First you will open the tmmregister URL scheme, supplying:

• application_id: String, your assigned application ID from Trimble
• returl: the callback URL for your own app that TMM will open when the registration operation is complete.

Swift

var params: [String: String] =
[
  "application_id": myApplicationID,
  "returl": "ThisAppCallback://com.mycompany.ThisApp"
]

let jsonData = try JSONSerialization.data(withJSONObject: params, options: [])
let jsonString = String(data: jsonData, encoding: .utf8)
let base64Encoded = jsonString?.data(using: .utf8)?.base64EncodedString()
let customUrl = URL(string: "tmmregister://?" + base64Encoded!)!
UIApplication.shared.open(customUrl) { (success) in
if success{
  // The URL was delivered successfully
}

Objective-C

NSDictionary *params = @{
  @"application_id": myApplicationID,
  @"returl": @"ThisAppCallback://com.mycompany.ThisApp"
};

NSData *jsonData = [NSJSONSerialization dataWithJSONObject:params options:0 error:nil];
NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
NSString *base64Encoded = [jsonString dataUsingEncoding:NSUTF8StringEncoding].base64EncodedString;
NSURL *customUrl = [NSURL URLWithString:[NSString stringWithFormat:@"tmmregister://?%@", base64Encoded]];
[[UIApplication sharedApplication] openURL:customUrl options:@{} completionHandler:^(BOOL success) {
  if (success) {
    // The URL was delivered successfully
  }
}];

Parse the Response

When TMM has finished it will return control back to your application by opening the previously provided callback url (returl). Add code to your app delegate to handle the incoming callback url.

Swift

func application(_ application: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey : Any] = [:] ) -> Bool {

    do {
      let query = url.query()!
      let data = Data(base64Encoded: query)!
      let jsonObject = try JSONSerialization.jsonObject(with: data, options: [])
      let results = (jsonObject as? [String: String])!

      // registrationResult:
      // OK: Your app is registered
      // Unauthorized: TMM was not able to verify the Application ID
      // NoNetwork: There is not internet connection
      let registrationResult = results["registrationResult"]!
      // localhost port for WebSocket Locations, Version 1
      let locationPort = Int(results["locationPort"]!)
      // localhost port for WebSocket Locations, Version 2
      let locationV2Port = Int(results["locationV2Port"]!)

      // The REST API is at $"WS://localhost:{apiPort}"
      let apiPort = Int(results["apiPort"]!)

      return true;
    } catch {
      return false;
    }
}

Objective-C

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    NSURLComponents *components = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
    NSString *query = components.query;
    NSData *data = [[NSData alloc] initWithBase64EncodedString:query options:0];
    NSDictionary *results = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
    NSString *registrationResult = results[@"registrationResult"];
    NSNumber *locationPort = results[@"locationPort"];
    NSNumber *locationV2Port = results[@"locationV2Port"];
    NSNumber *apiPort = results[@"apiPort"];

    return YES;
}