IFTTT Android SDK
Overview
IFTTT Android SDK is a library that helps facilitate the integration of the IFTTT API. you can find the documentation of the API here.
The SDK is designed to be a lightweight wrapper around the REST API, with predefined data structures and JSON adapters to help developers better use the API in their apps.
Dependencies
This SDK uses the following libraries as dependencies:
Requirement
Android SDK version 15 or higher.
Download
You can download the latest AAR here or via Gradle:
implementation 'com.ifttt:ifttt-sdk-android:0.0.1'
Example app
There is an example app in this repository to demonstrate how to use the SDK and your backend to integrate the IFTTT API on Android. You can find the example app here.
Get started
IftttApiClient
IftttApiClient
is the main entrance point to access to the SDK. In your app, call IftttApiClient.getInstance()
to get the singleton instance of the class. Then you can call the following methods for different APIs:
appletsApi()
: APIs for listing Applets or a single Applet from a service.appletConfigApi()
: APIs for enabling and disabling an Applet.userApi()
: API for retrieving IFTTT service and account information for the authenticated user.
For example, to get a list of Applets for your service:
AppletsApi appletsApi = IftttApiClient.getInstance().appletsApi();
appletsApi.listApplets("your-service-id", AppletsApi.Platform.android, AppletsApi.Order.enabled_count_asc)
.execute(new PendingResult.ResultCallback<List<Applet>>() {
@Override
public void onSuccess(List<Applet> applets) {
// Show Applets UI.
}
@Override
public void onFailure(ErrorResponse errorResponse) {
// Show error UI.
}
});
Key components
Data structure
The SDK provides the basic data structure for the data returned from the IFTTT API: Applet, Service and User. It also includes a few utility methods and tweaks for easier development. For more details of the data structure, please see the API documentation.
- Applet:
getPrimaryService
method that returns the primary service for the Applet.getEmbedUri
method returns a URI object for opening the Applet activation web UI.
- Service: the
brandColor
field is converted from the string representation to the integer representation of the color value.
Authentication
Some operations can be done without user authentication, such as fetching your service’s Applets. However, to get user-specific status (enabled vs. disabled), or to change an activated Applet’s status, you need to provide the IFTTT SDK with an IFTTT user token. You should fetch such a token on your backend service using the "Get a user token" API. See here for the example service’s implementation.
Once you have the user token, call IftttApiClient#setUserToken
method to attach it to the instance, and all subsequent API calls will be authenticated with the user token.
Some behavior changes to the API when there is no user token presented:
AppletsApi#listApplets
andAppletsApi#showApplet
will return Applet data withuser_status = unknown
.AppletConfigApi#enableApplet
andAppletConfigApi#disableApplet
will not work without user authentication or if the Applet’s currentuser_status
isnever_enabled
.UserApi#user
will return a User object withauthenticationLevel = none
and withoutservice_id
oruser_login
.
To clear the user token, call IftttApiClient#clearUserToken
method.
Invite code
If your service has not yet been published on IFTTT, you should provide the invite code to the IftttApiClient
to the SDK for full access to the IFTTT API. You can find your invite code under Invite URL on the Service tab on the IFTTT platform.
Once you have the invite code, call the IftttApiClient#setInviteCode
method to attach it to the instance, and all of the API requests will have it as a header.
To clear the invite code, call the IftttApiClient#clearInviteCode
method.
Applet activation
If an Applet has user state State.unknown
or State.never_enabled
, it can be activated through IFTTT web UI. For this, we strongly recommend using Chrome Custom Tabs to provide the best experience to your users. You can check out the example app to see details about how to use it.
Applet#getEmbedUri
constructs a URI object that can be used in web view or browser to start the Applet activation flow with the following parameters:
redirectUri
(required) is the URL that should be opened and return users to your app once the Applet activation process is complete. It must be registered on the IFTTT platform.user_id
(required) is the user id of the current user on your service. This will help us ensure that the user is logged into the correct IFTTT account and streamline the process of logging into or signing up for IFTTT.email
(optional but encouraged) is the email address of the current user. If you include it, we can try to streamline the process of logging into or signing up for IFTTT by looking for a matching account or prefilling the signup form. We won’t store the address unless the user signs up with it.inviteCode
(optional) should be included if your service is not published yet.
IMPORTANT: We don’t encourage you to open this URL directly. Instead, you should generate (likely in cooperation with your backend service) a URL that will sign in the user to your service in the web session so that connecting your service is simple once they create an IFTTT account.
For example, the service used by the example app has an authenticated API endpoint that accepts a redirect_to
as a URL. It returns a URL that, if opened, sets a session cookie to login the current user, then immediately redirects (with a 302) to the URL specified by redirect_to
. The example app then opens this URL. When it’s time to connect your service to IFTTT, the user does not then need to sign into their account, but is instead sent straight to the OAuth authorization page.