Articles in this section

Deep Links and Custom Actions with Iterable's React Native SDK

It's often useful to link directly from your marketing campaigns to specific content in your mobile apps. To make this possible, Iterable supports deep links and custom actions. Deep links can open a particular screen in an app, and custom actions can have the app take a specific action of some kind.

Iterable's React Native SDK supports deep links and custom actions, as described in this document.

Table of contents

Prerequisites

Before following the instructions in this guide:

When it comes to deep links, there are a few related terms that can be easily confused:

  • Deep links - URLs that link to particular content that can your app can open if it's installed, and a web browser can open otherwise. For example: https://myapp.com/products/widget.

    Iterable can include deep links in email, in-app message and push notification campaigns.

    When they're included in an email campaign, Iterable rewrites deep links so that they point to your tracking domain (for example, https://links.myapp.com/a/...). When a user clicks this rewritten link in an email on their mobile device, your app (if installed) opens it. The app then calls back to the tracking domain, asking it to track the click and respond with the originally intended link destination (along with identifying information about the campaign and template that caused the user to click the link in the first place). The SDK then hands the link's final destination URL to your app's URL handler, which can deal with it as necessary.

    Iterable does not rewrite deep links for push notifications or in-app messages. In these cases, the SDK makes API calls to track link clicks after they're clicked, and the messages themselves contain information about the campaign and template they're associated with.

  • App links - Android's implementation of deep links, which allows you to open an Android app a link clicked somewhere outside of it (for example, opening the app by clicking a link in an email).

    WARNING

    Iterable's React Native SDK does not yet support App Links, so it's not possible to link from an email into an Android app built with Iterable's React Native SDK. However, the SDK does support deep links delivered by in-app messages and push notifications.

  • Universal links - The iOS implementation of deep links, which allows you to open an iOS app from a link clicked somewhere outside of it (for example, opening the app by clicking a link in an email). Iterable's React Native SDK supports Universal Links, but you'll first need to configure your app to support them.

The following sections describe how to support deep links and other URLs when using Iterable's React Native SDK.

URL handler

To handle deep links (and other URLs), Iterable calls the function stored in the IterableConfig object's urlHandler. Set this property on the IterableConfig you provide to the SDK's initialize method.

  • Property declaration:

    urlHandler?: (url: string, context: IterableActionContext) => boolean
    Parameter Name Description
    url The clicked URL.
    context Describes the source of the URL (push, in-app, or universal link) and information about any associated custom actions.

  • Description:

    Use this method to determine whether or not the app can handle the clicked URL. If it can, the method should navigate the user to the right content in the app and return true. Otherwise, it should return false to have the web browser open the URL.

  • Example:

    const config = new IterableConfig()
config.urlHandler = (url, context) => {
	if (url.match(/product\/([^\/]+)/i)) {
		this.navigate(match[1]);
		return true; // handled
	}
	return false; // not handled
}
Iterable.initialize('<YOUR_API_KEY>', config);

    This example searches for URLs that contain product/, followed by more text. Upon finding this sequence of text, the code displays the appropriate screen and returns true. When it's not found, the app returns false.

When the SDK resolves a deep link to determine its final destination (as described above), Iterable also provides attribution information: the campaign ID, template ID and message ID (specific send of a specific campaign to a specific user) that prompted the user to click the link. The React Native SDK stores this information, and you can access it later when you need to attatch attribution information to various method calls (event tracking, purchases, etc.).

Getting attribution info

To get the current attribution information (based on a recent deep link click), call the static getAttributionInfo method on the Iterable class.

  • Method declaration:

    static getAttributionInfo(): Promise<IterableAttributionInfo | undefined>

    This method returns a Promise. Use then to get the IterableAttributionInfo object that contains the relevant results.

  • Description:

    This method gets the attribution data for a recent deep link click.

  • Example:

    Iterable.getAttributionInfo().then((attributionInfo) => {
  Iterable.updateSubscriptions(
	null,
	[33015, 33016, 33018],
	null,
	null,
	attributionInfo.campaignId,
	attributionInfo.templateId
  );
});

    This example fetches the current attribution information (an IterableAttributionInfo object) and uses it to update the user's subscription preferences. The call to updateSubscriptions sets the user's unsubscribed channel IDs to [33015,33016,33018] and attributes this change to the campaignId and templateId stored in the attributionInfo info object.

Setting attribution info

To manually set the current attribution information so that it can later be used when tracking events, call the setAttributionInfo method on the Iterable class.

  • Method declaration:

    static setAttributionInfo(attributionInfo?: IterableAttributionInfo)
    Parameter Name Description
    attributionInfo Information about the campaign ID, template ID and message ID to use for attribution.

  • Description:

    For deep link clicks, Iterable sets attribution information manually. However, use this method to set it manually if you ever need to do so.

  • Example:

    const campaignId = 123;
const templateId = 456;
const messageId = "0fc6657517c64014868ea2d15f23082b";
const attributionInfo = new IterableAttributionInfo(campaignId, templateId, messageId);
Iterable.setAttributionInfo(attributionInfo);

    This call creates an IterableAttributonInfo object that stores the campaignId, templateId and messageId that represent the current attribution information. It then uses the setAttributionInfo method to save this information for future use.

Custom actions

Push notifications and in-app messages can include links (or action buttons) that make use of custom actions. These URLs describe particular actions your app can take (but a browser cannot open).

For example, a user might tap a push notification action button to acknowledge some sort of achievement, and the custom action associated with the URL might change the app's styling to reflect this.

Defining custom actions

A custom action URL has format action://customActionName: an action:// prefix, followed by a custom action name. Decide with your marketing team on a set of known custom actions your app should support.

WARNING

Earlier versions of the SDK used the itbl:// prefix for custom action URLs. The SDK still supports these custom actions, but they are deprecated and will not be supported forever. Migrate to action:// as it's possible to do so.

Custom action handler

To handle custom action URLs with Iterable's React Native SDK, provide a function to the customActionHandler property on the IterableConfig object passed to the SDK's initialize method. Iterable calls this method when a user clicks a URL, passing in the URL and other contextual information.

  • Property declaration:

    customActionHandler?: (action: IterableAction, context: IterableActionContext) => boolean
    Parameter Name Description
    action The action to handle.
    context Information about where the action was invoked.

  • Description:

    Use this method to determine whether or not the app can handle the clicked custom action URL. If it can, it should handle the action and return true. Otherwise, it should return false.

  • Example:

    const config = new IterableConfig()
config.customActionHandler = (action, context) => {
	if (action.type == "achievedPremierStatus") {
		// For this action, update the app's styles
		this.updateAppStyles("premier");
		return true; 
	}
	return false; 
}
Iterable.initialize('<YOUR_API_KEY>', config);

    This example responds to the action://achievedPremierStatus custom action URL by updating the app's styles and return true. Since this is the only custom action handled by the method, it returns false for anything else.

Further reading

Related articles

Comments

0 comments

Article is closed for comments.