Action handling

Types of actions in campaigns

Campaigns can have three action types:

OPEN APP - This option opens your app after clicking the notification. If the app is already in the foreground, clicking the notification doesn’t have any effect.
OPEN URL - This option opens a URL. Depending on your implementation, the link is opened in the browser by default or in your custom implementation, such as a webview in your application.
DEEP LINKING - This option lets you transfer users to a specific view in your app by system methods or by your custom implementation.

Handling actions from campaigns

You can handle actions from campaigns by using dedicated listeners and delegates:

If you don’t implement listener/delegate for handling actions in your customized way:

The SDK runs the default browser with the requested URL address for OPEN URL.
The SDK tries to handle the deep link in the host app by a system method for DEEP LINKING.

Note: On iOS, deep links require special attention. The default SDK behaviour uses the UIApplication.shared.canOpenURL(_:) method. That method verifies a whitelist of deep links in LSApplicationQueriesSchemes key in the \*.plist file. Read more in Apple documentation.

Android

You can handle actions from each type of campaign in your own customized way by using OnInjectorListener methods.

The OnInAppListener monitors when a JS method is used in an in-app message.

In extended methods for handling OPEN URL and DEEP LINKING, the following parameters are available:

URL value from the action of the activity.
Deep link value from the action of the activity.
InjectorSource: enum that defines the kind of activity from the action that was sent.

Configuration

Make your activity available for deep linking by including the following parameters in your AndroidManifest:

   <activity
      android:name=".ui.linking.DeepLinkingActivity">
      <intent-filter>
          <action android:name="syne://test" />
          <category android:name="android.intent.category.DEFAULT" />
           <data 
              android:scheme="syne"
              android:host="test" />
      </intent-filter>
   </activity>

For the configuration above, the sample deep link parameter is syne://test?param=value, where:

syne and test are the scheme and host provided in the intent filter.
parameter is the parameter name.
value is the parameter value.

Important: Your action name must be the same as your URI scheme and host.

Optional: Define an activity to be called after closing the activity that was initiated by deep linking. Provide an additional intent category:

   <activity
      android:name=".ui.linking.DeepLinkingActivity"
      android:parentActivityName=".ui.linking.ParentDeepLinkingActivity">
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data
              android:host="test"
              android:scheme="syne" />
      </intent-filter>
   </activity>

Tip: If your deep link doesn’t contain the :// characters after the scheme, it is treated as a regular string key and set to the Intent’s action.
This means that you can set an action name (in your AndroidManifest activity’s intent filter) to any string and then match it with the provided deep link.

Sample implementation

InjectorActionHandler.setOnInjectorListener(new OnInjectorListener() {
  @Override
  public boolean onOpenUrl(InjectorSource source, String url) {
    //your implementation of OPEN URL action
    return false;
  }

  @Override
  public boolean onDeepLink(InjectorSource source, String deepLink) {
    //your implementation of DEEP LINKING action
    return false;
  }
});

Important: If you don’t configure a custom action, the SDK applies the default behavior, as described earlier.

iOS

You can handle actions from each type of campaign in your own customized way by using SyneriseDelegate methods.

The InjectorInAppMessageDelegate monitors when a JS method is used in an in-app message.

In extended methods for handling OPEN URL and DEEP LINKING, the following parameters are available:

URL value from the action of the activity.
Deep link value from the action of the activity.
SyneriseActivity: enum that defines the kind of activity from the action that was sent.
SyneriseActivityCompletionHandler: block/closure that defines whether an activity should be hidden or not and what code should be invoked after.

Sample implementation of OPEN URL action

This way you can, for example, check the type of activity or use your own webview to show the web page.

// MARK: - SyneriseDelegate

func snr_handledAction(url: URL, activity: SyneriseActivity, completionHandler: SyneriseActivityCompletionHandler) {
  if activity == .walkthrough {
    completionHandler(.none, {
      if UIApplication.shared.canOpenURL(url) {
        if #available(iOS 10, *) {
            UIApplication.shared.open(url, options:[:], completionHandler:nil)
        } else {
            UIApplication.shared.openURL(url)
        }
      }
    })

    return
  }

  if activity == .banner || activity == .simplePush {
    completionHandler(.hide, {
      //...
    })

    return
  }
}

Sample implementation of DEEP LINKING action

This way you can, for example, check the type of activity and handle your deep link in a custom way.

// MARK: - SyneriseDelegate

func snr_handledAction(deepLink: String, activity: SyneriseActivity, completionHandler: SyneriseActivityCompletionHandler) {
  if activity == .walkthrough {
    completionHandler(.none, {
      goToHelpWithId(deepLink)
    })

    return
  }

  if activity == .banner {
    completionHandler(.hide, {
      goToPromotionFromDeepLink(deepLink)
    })

    return
  }

  if activity == .simplePush {
    completionHandler(.hide, {
      goToMessageWithId(deepLink)
    })

    return
  }
}

System method to handle deep links

The code below presents a system method sample implementation to handle deep links. See Apple Developer - UIApplication.open(_:options:completionHandler:) method for more details.

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  //...
  //other methods
  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let sourceApplication: String? = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
    let annotation: Any? = options[UIApplication.OpenURLOptionsKey.annotation]
        
    let handled: Bool = ApplicationDelegate.shared.application(app, open: url, sourceApplication: sourceApplication, annotation: annotation)
      if handled == true {
        return true
      }
        
      if url.scheme == "sample-swift" {
        applicationController.getMainCoordinator()?.didReceiveDeeplink(host: url.host!, pathComponents: url.pathComponents)
        return true
      }
        
    return false
  }
}

Important: If you don’t configure a custom action, the SDK applies the default behavior, as described earlier.

React Native

You can specify your custom action when a customer interacts with your simple push, banner, walkthrough, or in-app message.

You can handle actions from each type of campaign in your own customized way by using InjectorListener methods.

In listener methods for handling OPEN URL and DEEP LINKING, the following parameters are available:

URL value from the action of the activity.
Deep link value from the action of the activity.
SyneriseSource: enum that defines the kind of activity from the action that was sent.

Synerise.Injector.setListener({
  onOpenUrl: function(url, source) {
    //your implementation of OPEN URL action
    Linking.openURL(url);
  },
  onDeepLink: function(deepLink, source) {
    //your implementation of DEEP LINKING action
  }
  //...
  //other listener's methods
});

Important: If you don’t configure a custom action, the SDK applies the default behavior, as described earlier.

Flutter

You can specify your custom action when a customer interacts with your simple push, banner, walkthrough, or in-app message.

You can handle actions from each type of campaign in your own customized way by using InjectorListener methods.

In listener methods for handling OPEN URL and DEEP LINKING, the following parameters are available:

URL value from the action of the activity.
Deep link value from the action of the activity.
SyneriseSource: enum that defines the kind of activity from the action that was sent.

Synerise.injector.listener((listener) {
  listener.onOpenUrl = (url, source) {
    //your implementation of OPEN URL action
  };
  listener.onDeepLink = (deepLink, source) {
    //your implementation of DEEP LINKING action
  };
  //...
  //other listener's methods
});

Important: If you don’t configure a custom action, the SDK applies the default behavior, as described earlier.

Universal linking

Universal links help your users follow links to content in your app or to your website. When they open a universal link, their mobile OS checks whether any installed app is registered for that domain. If there is no configured application URL for a given path, the user stays on the website.

Important: In order to send universal links from Synerise, you must use the OPEN URL action in your campaign configuration on Synerise UI.

Android

In order to implement universal links, you need to configure them in the AndroidManifest.xml file in your application.

Add data to your activity in order to connect a URL with a screen.

<activity
  android:name=".ui.dev.tracker.TrackerViewActivity"
  android:screenOrientation="portrait">
  <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data
          android:host="synerise.com"
          android:pathPrefix="/tracker"
          android:scheme="https" />
      <!-- note that the leading "/" is required for pathPrefix-->
  </intent-filter>
</activity>

iOS

To implement universal links:

On your app identifier, enable Associated Domains
In your Xcode project, enable Associated Domain (in capabilities).

Configure your website to host the apple-app-site-association file.

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appID": “<<TEAM_ID>>.com.synerise.sdk.sample",
            "paths": [
              "*"
            ]
          }
        ]
      }
    }

Configure your app to handle universal links.

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
    // handle url and run app action that you want
  }
  
  return true
}

For more details, see Apple Developer - Universal Links for Developers.

Handling actions from campaigns (older SDK versions)

Android (version 5.12.0 and lower)

You can handle actions in your own customized way by using:

InjectorListener methods for banner and walkthrough
InAppMessageListener methods for in-app messages.

Important: You cannot handle actions in your own customized way for simple push. It works as default, so OPEN URL opens the browser and DEEP LINKING opens an activity associated with this deep link.

Configuration

Make your activity available for deep linking by including the following parameters in your AndroidManifest:

   <activity
      android:name=".ui.linking.DeepLinkingActivity">
      <intent-filter>
          <action android:name="syne://test" />
          <category android:name="android.intent.category.DEFAULT" />
           <data 
              android:scheme="syne"
              android:host="test" />
      </intent-filter>
   </activity>

Important: Your action name must be the same as your URI scheme and host.

Optional: Define an activity to be called after closing the activity that was initiated by deep linking. Provide an additional intent category:

   <activity
      android:name=".ui.linking.DeepLinkingActivity"
      android:parentActivityName=".ui.linking.ParentDeepLinkingActivity">
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data
              android:host="test"
              android:scheme="syne" />
      </intent-filter>
   </activity>

For the configuration above, the sample deep link parameter is syne://test?param=value, where:

syne and test are the scheme and host provided in the intent filter.
parameter is the parameter name.
value is the parameter value.

Important: Your action name must be the same as your URI scheme and host.

Optional: Define an activity to be called after closing the activity that was initiated by deep linking. Provide an additional intent category:

   <activity
      android:name=".ui.linking.DeepLinkingActivity"
      android:parentActivityName=".ui.linking.ParentDeepLinkingActivity">
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />
          <data
              android:host="test"
              android:scheme="syne" />
      </intent-filter>
   </activity>

Simple Push

The SDK handle those actions by default, so OPEN URL opens the browser and DEEP LINKING opens an activity associated with this deep link.

The SDK allows you to handle those actions. By default, OPEN URL opens the browser and DEEP LINKING opens an activity associated with this deep link.

You can specify your custom action when a customer interacts with your banner or walkthrough.

Important: The callbacks presented below work only with banner and walkthrough.

Receive data from the deep link by implementing the following code:

String data = intent.getDataString();
if (data != null) {
   Uri uri = Uri.parse(data);
   value = uri.getQueryParameter("param");
}

If you want to implement your own behavior, refer to the following code:

public class App extends Application implements OnInjectorListener {
    @Override
    public void onCreate() {
        super.onCreate();

        Synerise.Builder.with(this, syneriseClientApiKey, appId)
                        .notificationIcon(R.drawable.ic_notification_icon)
                        .build();
    }

    @Override
    public boolean onOpenUrl(InjectorSource source, String url) {
        //your implementation of OPEN URL action
        SystemUtils.openURL(this, url); // default behavior
        return source != InjectorSource.WALKTHROUGH; // default behavior
    }

    @Override
    public boolean onDeepLink(InjectorSource source, String deepLink) {
      //your implementation of DEEP LINKING action
        SystemUtils.openDeepLink(this, deepLink); // default behavior
        return source != InjectorSource.WALKTHROUGH; // default behavior
    }

onOpenUrl(InjectorSource, String) - callback is fired when a customer interacts with the OPEN URL action. Returns true if the activity should be closed after the action executes, false otherwise.
onDeepLink(InjectorSource, String) - callback is fired when a customer interacts with the DEEP LINKING action. Returns true if the activity is closed after the action is executed, false otherwise.

In-app messages

The SDK allows you to handle those actions. By default, an OPEN URL opens the browser and DEEP LINKING opens an activity associated with this deep link.

You can specify your custom action when a customer interacts with your in-app messages.

Important: The callbacks presented below work only with in-app message.

If you want to implement your own behavior, refer to the following code:

public static OnInAppListener NULL = new OnInAppListener() {
  @Override
  public void onHandledOpenUrl(InAppMessageData inAppMessageData) {
    //your implementation of OPEN URL action
  }

  @Override
  public void onHandledOpenDeepLink(InAppMessageData inAppMessageData) {
    //your implementation of DEEP LINKING action
  }
};

onHandledOpenUrl(InAppMessageData) - callback is fired when a customer interacts with the OPEN URL action. Returns true if the activity is closed after the action is executed, false otherwise.
onHandledOpenDeepLink(InAppMessageData) - callback is fired when a customer interacts with the DEEP LINKING action. Returns true if the activity is closed after the action is executed, false otherwise.

React Native (version 0.17.0 and lower)

Important: React Native SDK (version 0.17.0 and lower) cannot handle actions by default, you must implement it.

You can handle actions in your own customized way by using:

InjectorListener methods for simple push, banner and walkthrough
InjectorInAppMessageListener methods for in-app messages.

You can specify your custom action when a customer interacts with your simple push, banner, or walkthrough.

Important: On Android, you cannot handle actions in your own customized way for simple push. It works as default so OPEN URL opens the browser and DEEP LINKING opens an activity.

Synerise.Injector.setListener({
  onOpenUrl: function(url) {
    //your implementation of OPEN URL action
    Linking.openURL(url);
  },
  onDeepLink: function(deepLink) {
    //your implementation of DEEP LINKING action
  }
  //...
  //other listener's methods
});

In-app messages

You can specify your custom action when a customer interacts with your in-app messages.

Synerise.Injector.setInAppMessageListener({
  onOpenUrl: function(data, url) {
    //your implementation of OPEN URL action
  },
  onDeepLink: function(data, deepLink) {
    //your implementation of DEEP LINKING action
  },
  //...
  //other listener's methods
});

Flutter (version 0.7.4 and lower)

Important: Flutter SDK (version 0.7.4 and lower) cannot handle actions by default, you must implement it.

You can handle actions in your own customized way by using:

InjectorListener methods for simple push, banner and walkthrough
InjectorInAppMessageListener methods for in-app messages.

You can specify your custom action when a customer interacts with your simple push, banner, or walkthrough.

Important: On Android, you cannot handle actions in your own customized way for simple push. It works as default so OPEN URL opens the browser and DEEP LINKING opens an activity.

Synerise.injector.listener((listener) {
  listener.onOpenUrl = (url) {
    //your implementation of OPEN URL action
  };
  listener.onDeepLink = (deepLink) {
    //your implementation of DEEP LINKING action
  };
  //...
  //other listener's methods
});

In-app messages

You can specify your custom action when a customer interacts with your in-app messages.

Synerise.injector.inAppMessageListener((listener) {
  listener.onOpenUrl = (data, url) {
    //your implementation of OPEN URL action
  };
  listener.onDeepLink = (data, deepLink) {
    //your implementation of DEEP LINKING action
  };
  //...
  //other listener's methods
});

Action handling

Types of actions in campaigns

Handling actions from campaigns

Android

Configuration

Sample implementation

iOS

Sample implementation of OPEN URL action

Sample implementation of DEEP LINKING action

System method to handle deep links

React Native

Flutter

Universal linking

Android

iOS

Handling actions from campaigns (older SDK versions)

Android (version 5.12.0 and lower)

Configuration

Simple Push

Banner and Walkthrough

In-app messages

React Native (version 0.17.0 and lower)

Simple Push, Banner and Walkthrough

In-app messages

Flutter (version 0.7.4 and lower)

Simple Push, Banner and Walkthrough

In-app messages

We are sorry to hear that

Awesome!