Table of Contents
Communication between iOS apps is very limited. All iOS apps are sandboxed which means that direct communication is not possible at all. The following are allowed ways to communicate:
- Calling other Apps using the Share Task
- Calling Alloy Actions using Alloy Action Extension
- Using URL Scheme
Calling other Apps using the Share Task
It is possible to call other apps from Alloy's workflow using a Share task. This task allows to share data using the Share Sheet. In the Share Sheet the user will be able to select other apps' activities that can consume data provided by Alloy's workflows. If the user selects an activity that returns some data - it will be consumed (since Alloy v2.) and returned as the task's output.
Calling Alloy Actions using Alloy Action Extension
Alloy includes a new Action Extension (since Alloy v2.) that allows launching Alloy's actions right from other apps. This allows to utilize or alter data provided by other apps.
The action's "Input" property should be specified to mark an action as capable of accepting certain data types. For example, an action working with photos should have the "Input" = "Photo". By default, action's output will be returned to the host app, potentially changing shared data. To avoid this (if it's not desired) the action's "Output (Extension)" property should be turned OFF.
Also, there is special support for Safari browser that allows to view or change page's URL or content. To make a Safari extension an action should have the "Property List" as the input type. When launched, such an action will receive a dictionary containing the
content properties as input. To change page's URL or content an action should output a dictionary containing respective new values.
To allow taking only page's URL from Safari an action should have the "URL" as input. For example, to add a bookmark in Alloy - choose the "Bookmark" action and then choose "Install". Note, in that case action's output is ignored
Using URL Scheme
This topic describes how to implement bidirectional communication between Alloy and other iOS apps using URL Scheme.
Launching Alloy from other Apps
Alloy declares the alloy URL Scheme and handles URLs that use that scheme.
To use that approach, you should form a correct URL according to the protocol supported by a target app and ask the system to open it. Sample code would be:
NSURL* url = [NSURL URLWithString:@"alloy://"]; [[UIApplication sharedApplication] openURL:url];
The following URLs are supported by Alloy.
Launch Alloy Actions
alloy://<UID | Short-UID>[?Arguments]
You can obtain link to any action by turning ON the Edit mode, taping the Share button and choosing the "Copy Link" action.
Arguments is a standard HTML query string like:
You can use arguments to pass variable values to the action.
Sample link to an action to send SMS with the "Please call me" text would be:
By default, Alloy prompts the user to confirm launch of actions. To turn OFF that prompt add alloy-ask=NO to the arguments:
You can use the paste system action to perform some action with clipboard contents:
Import Alloy Actions
To import an action stored somewhere in the Cloud:
You can obtain a copy of any action by turning ON the Edit mode, taping the Share button and choosing the "Share" command.
To import several actions stored somewhere in the Cloud:
You can obtain copies of several actions by moving them to a folder, turning ON the Edit mode fro that folder, taping the Share button and choosing the "Share" command.
Launching other Apps from Alloy Actions
You can launch other apps from Alloy actions using an "Open URL" task. For example, to launch Yelp app the yelp4:// URL should be opened.
Note: URL Scheme and URL query are specific to each particular app. Currently it is not possible to discover them automatically using either Apple's or third-party services. So you should check corresponding resources provided by developers of the apps of interest to find supported URL Scheme and query.
Alloy fully supports x-callback-url specification to allow bi-directional communication between apps.
Launch Alloy Actions with x-callback-url
To launch an Alloy action with x-callback-url you can use slightly modified link format:
alloy://x-callback-url/<UID | Short-UID>[?Arguments]
All x-callback-url arguments are supported:
- x-source - name of the caller app
- x-success - URL to be opened when action is successfully completed
- x-error - URL to be opened when action is failed
- x-cancel - URL to be opened when action is cancelled
After the action is completed the user will be prompted to return to the caller app, as specified by x-callback-url arguments.
Sample link would be:
Action's Output Arguments ("Edit Action | Options | Output Arguments") should be used to return some data from Alloy to a caller app. After the action it completed with success, it will modify x-success URL to to list output arguments there. For example, calling a "Tip Calculator" action, having total=$(total) as Output Arguments:
would result a someapp://?total=100 call.
Launch other Apps with x-callback-url
To support x-callback you would need to add $(s:x-callback)macro to task's URL:
The $(s:x-callback) macro takes care about providing all the required arguments and data to let the target app to properly return to Alloy.
If an "Open URL" task is not the last task in the action and its URL conforms to x-callback-url specification - such action will be suspended and all its data will be persisted. Then target app will be launched. Once target app completes its job and calls back Alloy app using x-success URL - suspended action can be resumed and will continue to perform remaining workflow. By default, the user will be prompted to resume suspended action. You can control this via "Settings | General Prompt to Resume Actions".
If s target app does not return back to Alloy using x-success, x-error or x-cancel URLs then suspended action will be orphaned. To free space and remove such suspended actions use the "Settings | General | Remove Temporary Files" option.
To return some data back to Alloy one of the following approaches can be used:
- Target app can alter passed x-success, x-error or x-cancel URLs and return URL-encoded textual data as HTML query e.g. alloy://resumeAction?return=some-text. When the caller action is resumed, that data will be accessible via corresponding runtime variables.
- Target app can pass data to return to clipboard to let a caller action to access it via s:clipboard variable.
Make your App Listed
Developed new and wonderful app? Found a very useful app? Let us know and we would consider that app for adding to our list of supported apps.
Note, the app must provide useful functionality via custom URL Scheme.