Example (One-way communication)

The most basic usage for a URL scheme is to launch another application, passing data to it. Through the adoption of x-callback-url, we hope the format and documentation of available URL scheme method will become more standardized.

In this example, a user has composed a short bit of text in a fictitious app, SourceApp. SourceApp wishes to forward this text to a Twitter client, TargetApp, to take advantage of that app’s Twitter integration. To do this, SourceApp should test for the presence of TargetApp’s URL scheme, using UIApplication’s canOpenURL method, then open the following URL using UIApplication’s openURL method:

targetapp://x-callback-url/updateStatus?
   x-source=SourceApp&
   text=[User inputted string]

(Note: callback URLs in parameters should be encoded. They were left decoded for legibility)

When the URL is launched, TargetApp will open and be informed of the URL and handle it according.

Example (Two-way communication)

The following is a trivial “Hello World” example of a conversation between two fictitious iOS apps, “SourceApp” and “TargetApp” using the x-callback-url specification.

In this example, SourceApp is the current running app, and has registered the URL scheme “sourceapp://”. TargetApp is another app installed on device, which has registered the “targetapp://” URL scheme.

TargetApp is a translation app. The developer of TargetApp has defined an x-callback-url action to translate a word passed to a different language, and return the result to the calling app.

SourceApp wants to provide a greeting to a user in a different language, and if it is installed, will use TargetApp’s x-callback-url action. To do this, SourceApp should test for the presence of TargetApp’s URL scheme, using UIApplication’s canOpenURL method, then open the following URL using UIApplication’s openURL method:

targetapp://x-callback-url/translate?
   x-success=sourceapp://x-callback-url/acceptTranslation&
   x-source=SourceApp&
   x-error=sourceapp://x-callback-url/translationError&
   word=Hello&
   language=Spanish

(Note: callback URLs in parameters should be encoded. They were left decoded for legibility)

When the URL is opened, iOS will launch TargetApp, and pass the URL as arguments (see implementation for details of handling incoming URLs). TargetApp will parse the URL, identify the action requested, and translate “Hello” to “Spanish” as passed in the parameters. The “translate” action and it’s parameters are all specific to TargetApp and should be documented by the developer. If TargetApp is successful in translating the word, it will then call the URL in the x-callback parameter to return the result to SourceApp.

sourceapp://x-callback-url/acceptTranslation?
   x-source=TargetApp&
   word=Hola

In case of an error, TargetApp would return control to SourceApp with the following URL:

sourceapp://x-callback-url/translationError?
   x-source=TargetApp&
   errorCode=code&
   errorMessage=message

If the “x-error” parameter was excluded, TargetApp should not return to SourceApp and would report the error directly to the user. The “x-“ prefix should not be used on action parameters, but be reserved for additional parameters that may be defined by the x-callback-url specification.

To learn more, check out the Examples and Implementation pages.