URL Structure

[scheme]://[host]/[action]?[x-callback parameters]&[action parameters]

scheme

The scheme should be a unique string identifier the target app. URL schemes are registered with iOS via an app’s Info.plist file. To support receiving x-callback-url message, an app must register a protocol with iOS. If your app uses x-callback-url, it is recommend you register a url scheme specifically for x-callback-url support, so that a source app can test for the registration of the scheme and ensure support is present.

host

URLs will be identified by the use of “x-callback-url” as the host portion of the URL.

action

The remaining portion of the URL path after the version make up the name of the action to be executed in the target app. These actions will vary by app and should be documented by the developer of the app supporting x-callback-url.

x-callback Parameters

x-callback-url defines several parameters with specific purposes, all of which are optional. These parameters should be passed as query args in the URL, in the format “key1=value1&key2=value2”. All values should be URL encoded strings.

x-source : The friendly name of the source app calling the action. If the action in the target app requires user interface elements, it may be necessary to identify to the user the app requesting the action.
x-success : If the action in the target method is intended to return a result to the source app, the x-callback parameter should be included and provide a URL to open to return to the source app. On completion of the action, the target app will open this URL, possibly with additional parameters tacked on to return a result to the source app. If x-success is not provided, it is assumed that the user will stay in the target app on successful completion of the action.
x-error : URL to open if the requested action generates an error in the target app. This URL will be open with at least the parameters “errorCode=code&errorMessage=message”. If x-error is not present, and a error occurs, it is assumed the target app will report the failure to the user and remain in the target app.
x-cancel : URL to open if the requested action is cancelled by the user. In the case where the target app offer the user the option to “cancel” the requested action, without a success or error result, this the the URL that should be opened to return the user to the source app.
Action Parameters

In addition to any of the optional parameters defined by x-callback-url, the query arguments can contain action parameters specific to target app’s supported actions. These parameters will be defined by the developer of the app supporting x-callback-url. 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.

Security Concerns

Because URL schemes open pathways to the data stored in your app, it is recommended that you carefully consider security when implementing URL schemes–whether they conform to the x-callback-url specification or not.

How to implement security is not covered by the specification, as the requirements vary greatly for different app, but, in general, URL schemes actions which perform destructive operations, post to services outside the app, or similar “dangerous” actions should require user-confirmation in-app to be sure the user has not unintentionally tapped on a malicious URL. Other mechanisms such as password keys, or similar may make sense for specific use cases.