Implementing Deferred Deeplinking

Last Updated: Dec 07, 2016 02:36PM PST

Deferred Deeplinking App Implementation Guide

This guide describes the technical steps required the implement Apsalar Deferred Deeplinking feature as enabled by the Apsalar SDK (Android SDK 6.5+ and iOS SDK 7.2+).  For some recommendations and guidance on how you/your developer can test your deferred deeplinking SDK implementation, you can skip down to our testing section here.

The Apsalar Deferred Deeplinking solution allows the Apsalar SDK to receive a deeplink value from Apsalar servers on a start session SDK call.  These deeplink values are then provided to your app via "callbacks" from the Apsalar SDK. Therefore, the app developer must provide a callback method and register it with the SDK.  The Apsalar callback will provide a potential deeplink value in no more than 5 seconds.  If 5 seconds have elapsed, the SDK will call the callback with a "null" value.

Implementing an Android Callback

The Android callback is implemented as a Java interface. The interface signature is:
public interface DeferredDeepLinkHandler {
        Use this method to handle the deeplink passed by Apsalar SDK
        @param link a String representing the deeplink
    public void handleLink(String link);
And the callback registration method is:
public static void registerDeferredDeepLinkHandler(final Context c, final DeferredDeepLinkHandler handler)

Here is a sample implementation utilizing the interface and callback:

private void setupApsalar() {
    final Context context = this.getApplicationContext();

    //  Set deferred deeplink timeout to 30 seconds, starting 6.5.1 
    Apsalar.setDeferredDeepLinkTimeout(context, 30);

    // Create an anonymous inner class that implements DeferredDeepLinkHandler
    // This must be called before calling startSession
    Apsalar.registerDeferredDeepLinkHandler(context, new DeferredDeepLinkHandler() {
        public void handleLink(String s) {
            // Implement your code here

    Apsalar.startSession(context, "MyID", "My Key");
  • The callback registration must be performed before calling Apsalar.startSession.
  • It is highly recommended that the Apsalar.startSession calls are placed before other processes/library initializations for performance
  • If the SDK does not receive a deeplink within 5 seconds (due to network conditions), the SDK will call the handler and pass a "null" value.
  • Starting SDK 6.5.1, it is possible to configure the deeplink timeout up to 60 seconds. The valid value range is between 5 and 60 seconds. If the method is called with a value less than 5, it will use 5. Likewise if it is called with a value greater than 60, it will use 60. It is recommended to use the lowest threshold possible.

Implementing an iOS Callback

The iOS callback is implemented using Objective-C block:

The block signature is the following:
^void(NSString *deeplink)
And the registration method is:
+ (void)registerDeferredDeepLinkHandler:(void (^)(NSString *deeplink))handler
Here is an sample implementation utilizing the block and callback:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   // Register a deferred deeplink handler
   // This must be done before calling startSession
   [Apsalar registerDeferredDeepLinkHandler:^(NSString *deeplink) {
      NSLog(@"Received deeplink from Apsalar SDK: %@", deeplink);
      [self processDeeplink:deeplink];
   return YES;

- (void)applicationDidBecomeActive:(UIApplication *)application 
   [Apsalar startSession:@"MyID" withKey:@"MyKey"];

- (void)processDeeplink:(NSString *)deeplink {
   // Implement your code here

  • The callback registration must be performed before calling Apsalar startSession.
  • It is highly recommended that the Apsalar.startSession calls are placed before other processes/library initializations for performance
  • If the SDK does not receive a deeplink within 5 seconds (due to network conditions), the SDK will call the block and pass a "nil" value.
  • The block will called in the context of main thread, therefore it’s not appropriate to perform long running operations inside the block

Testing Deferred Deeplinking

We have detailed a few steps detailed here on how you can test to be sure your Apsalar account and app has been configured correctly to receive deferred deeplink values.  To test this, we recommend using network debugging tools such as Charles, Wireshark, or Fiddler.   We will be demonstrating our examples using Charles.  You can find our quick guide on using Charles, here.

Preparing for Each Test

Deferred deeplinking is only available for devices who have not yet installed the app.  As such, make sure the following is done before each test:
  • A deferred deeplink enabled SmartTag is available for test.
  • Apsalar does not have record of app installed on device. Resetting your advertising ID will guarantee this.  See here on how to reset your adverting ID.
  • App is uninstalled from the test device

Performing the Test

To perform the test, do the following:
  1. Start Charles and set up your test device to route network calls through Charles via the proxy. 
  2. ​Click on the deferred deeplink enabled SmartTag on your device.  Note that the redirect destination does not matter, as long as the SmartTag is clicked on the device.
  3. Install the app (either via the app store or side-loaded)
  4. Open the app
  5. Observe Apsalar SDK in Charles

Verifying the Results

Once you have performed the above test, you should see a Apsalar HTTP calls being made to  In particular, look for the Apsalar Start Session call being made to  
If your app is correctly set up to receive a deferred deeplink value from Apsalar servers, you will see a &ddl_enabled=true query parameter in the start request.  The absence of this value may mean that callback registration was not done properly, or the session is not eligible for deferred deeplinking due to network unavailability.  

If you've verified that &ddl_enabled=true is present in the request, you should see a payload being returned in the response and your configured deeplink value returned in "ddl" as below.  This value is the value made available in the callback registered with the Apsalar SDK.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found