Deep Linking

🔹 Tools to use: AppsFlyer, BFG SDK

What is Deep Linking?

A deep link is a generic term for any link that opens the game remotely, whether or not it is installed on the user's device. From the player's perspective, they will click a link on an offer, ad, or message and be sent straight to the game advertised by the link. There are two different types of deep links:

Referral links direct the user to an app (rather than a specific location in the app). If the app is installed on the device, the app will open. If it is not installed, then the user will be directed to the App Store to download the game.
Deferred Deep Links go to a specific location in the app, but cannot be executed immediately. If the app is not installed, the user will be prompted to install the game. Once installed and launched, a call-back is made to retrieve the deep link and execute it.

Games published by Big Fish use AppsFlyer to create and manage deep links through campaigns.

Pre-Requisite

Before continuing, ensure you meet the following pre-requisites:

Integrate the BFG SDK (Unity | Native Android | Native iOS)
Enable AppsFlyer

Receiving Deep Link Notifications (Unity only)

The Unity SDK includes the ability to deep link notifications. To listen for deep link notifications, you first need to register the deep link notifications defined in bfgCommon.cs:

void Start ()
{
  NotificationCenter.Instance.AddObserver(deeplink_notification_received, bfgCommon.NOTIFICATION_DEEPLINK_ONDEEPLINKRECEIVED);
}

// Triggered when the deep link notification is received
public void deeplink_notification_received(string notification) {
  Debug.Log (deeplink_notification_received: notification=" + notification);
}

Setting up Deep Links

The process to set up deep links depends on which BFG SDK you are using.

Unity SDK (Android Targets)

Set up intent filters

Your Big Fish producer will send you a code snippet of an intent filter to put into manifest file of your app. An intent filter determines the type of requests that come from another app component (such as AppsFlyer). To complete setup for deep links on Android, copy the intent-filter into the relevant <activity> on your AndroidManifest.xml file. The snippet contains the following values:

The host value, provided by your Big Fish producer.
The four-character pathPrefix, an auto-generated value from the AppsFlyer portal that is unique to your game.

Here is an example of the code snippet for an intent filter:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https"
    android:host="bfgsdk.onelink.me"
    android:pathPrefix="/yryN" />
</intentfilter>

Set up URI Scheme

A URI scheme is a URL that leads users directly to your game, and is required for AppsFlyer links to work in Facebook. Whenever a Universal Link fails to open the app, the URI scheme can be used as a fallback to open the application.

Your Big Fish producer will provide you with the scheme you need to define in your manifest file. Add another filter to your manifest that handles specific deep link schemes for your game. In the following example, the scheme is bfgsample. Include this filter right below the intent filter you previously added for AppsFlyer:

<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:scheme="bfgsample" />
</intent-filter>

Unity SDK (iOS Targets)

Set the Delegate to Receive Callbacks

Open the file, com.bfg.sdk/Runtime/Plugins/iOS/BFGUnityAppController.mm
In BFGUnityAppController.mm, add the following code to the didFinishLaunchingWithOptions method before initializing the BFG SDK:

extern "C"
{
  void BfgDeepLinkDelegateWrapper_setDeepLinkListener();
}
-(BOOL)application:(UIApplication*) application didFinishLaunchingWithOptions:(NSDictionary*) options
{
  BfgDeepLinkDelegateWrapper_setDeepLinkListener();

  // Initialize the BFG SDK here

  return YES;
}

Update the App Delegate to Use Universal Links

Open the file, com.bfg.sdk/Runtime/Plugins/iOS/BFGUnityAppController.mm
In BFGUnityAppController.mm, add another pass-through call to bfgManager, which will update the App Delegate to use universal links through AppsFlyer.

-(BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler;
{
  return [bfgManager applicationContinueUserActivity:userActivity restorationHandler:restorationHandler];
}

Add URI scheme to your plist

Your Big Fish producer will provide you with the scheme you need to define in your game configuration. In the following example, the scheme is bfgsample. The scheme is added to your game's plist file:

<key>CFBundleURLSchemes</key>
<array>
  <string>bfgsample</string>
</array>

Native Android SDK

Implement the bfgDeepLinkListener

Implement the bfgDeepLinkListener in your main bfgActivity:

public class AndroidExampleActivity extends bfgActivity implements bfgDeepLinkListener

Override the OnDeepLinkReceived callback

Override the onDeepLinkReceived callback to handle the received deep link:

public void onDeepLinkReceived(final String deepLink, Map<String,String> conversionData, final String error) {
  if (!TextUtils.isEmpty(deepLink)) {
    bfgLog.d(this.getLocalClassName(), "Deep link received: \n" + deepLink);
  } else if (!TextUtils.isEmpty(error)) {
    bfgLog.d(this.getLocalClassName(), "Deep link retrieve error: " + error + " from UA tracking provider");
  }
  // The UA tracking provider returned additional information about the deep link that launched
  // the app. Inspect its content to gain insight regarding the source of the link. For links
  // originated from Facebook the deepLinkString will always be null and you'll need to look
  // for the deeplink in the conversionData dictionary. Ask your producer for the specific field
  // you should be looking for in this dictionary.
  // An example payload for a basic Facebook link could look like:
  // conversionData = {
  //    "af_ad": "testadname",
  //    "af_deeplink": true,
  //    "af_sub1": "testsubpub",
  //    "af_sub2": "testplacement",
  //    "campaign": "testcampaign",
  //    "host": "sdktest",
  //    "is_retargeting": true,
  //    "media_source": "Social Facebook",
  //    "path": "/reward/coins/1000/abc123",
  //    "scheme": "bfgsample",
  //    "shortlink": "dlfbpost"
  // }
  // For this example, you might be interested in the 'path' field of the dictionary, where you could extract
  // a promo code or other meaningful information for your game.
  if (conversionData != null) {
    bfgLog.d(this.getLocalClassName(), "onDeepLinkReceived: conversion data: " + conversionData + " from UA tracking provider");
  }
}

Set listener callback

Set your listener callback with setDeepLinkListener in onCreate().

info

Set the listener callback before initializing the SDK to ensure that deep links are not missed.

bfgGameReporting.sharedInstance().setDeepLinkListener(this);

Set up intent filters

The host value, provided by your Big Fish producer.
The four-character pathPrefix, an auto-generated value from the AppsFlyer portal that is unique to your game.

Here is an example of the code snippet for an intent filter:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https"
    android:host="bfgsdk.onelink.me"
    android:pathPrefix="/yryN" />
</intentfilter>

Set up URI Scheme

<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:scheme="bfgsample" />
</intent-filter>

Referral URL / URI Scheme

You will get the shared scheme in the deepLinkString field if a referral URL opens your game. Nothing needs to be done by the game at this point since the goal of the referral is to simply open the app.

"deepLinkString": "bfgsample://",
"conversionData": {
    "af_dp": "bfgsample://",
    "link": "https://bfgsample.onelink.me/lmNv/dlfbpost"
}

First Launch Installation Attribution

When your game launches for the first time, you will receive an onDeepLinkReceived callback with information on the installation attribution. The deepLink parameter will be null unless the first launch resulted from a deferred deep link. The contents of the conversionData collection will vary, depending on whether the installation was organic, from a deep link, or a deferred deep link from one of our advertising partners, such as Facebook.

For example, an organic installation will provide the following conversionData:

"af_message": "organic install",
"af_status": "Organic",
"is_first_launch": "true"

For a full list of all the possible data provided in the conversionData collection, see Conversion data payloads and scenarios ↗️ in AppsFlyer's documentation.

Native iOS SDK

Implement the bfgDeepLinkListener

Set up your AppDelegate to conform to the bfgDeepLinkListener protocol:

@interface BFGUIKitExampleAppDelegate () <bfgPlacementDelegate, bfgManagerPauseResumeDelegate, bfgDeepLinkListener>

Next, setup the bfgDeepLinkListener listener before initializing the BFG SDK.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [bfgGameReporting setDeepLinkListener:self];
  [bfgManager startWithLaunchOptions:launchOptions parentViewController:myRootViewController];
}

Implement the onDeepLinkReceived callback

Confirm that your listener implements the onDeepLinkReceived:conversionData:error: method to retrieve any deep links that have been received:

#pragma mark - bfgDeepLinkListener

-(void) onDeepLinkReceived:(NSString * _Nullable)deepLinkString conversionData:(NSDictionary* _Nullable)conversionData error:(NSError * _Nullable)error
{
  if (error)
  {
      BFGUIKitExampleLog(@"An error occurred in the UA tracking provider. Error: %ld: %@", error.code, error.localizedDescription);
      return;
  }
  if (deepLinkString.length)
  {
      NSString *message = [NSString stringWithFormat:@"Deep link received: %@", deepLinkString];                      
      NSLog(@"[DeepLink]: %@", deepLinkString);
  }
  else
  {
      BFGUIKitExampleLog(@"The UA tracking provider didn't have a deep link for us");
  }
  // The UA tracking provider returned additional information about the universal link and/or deeplink
  // that launched the app. Inspect its content to gain insight regarding the source of the link.
  // For links originated from Facebook the deepLinkString will always be nil, and you'll need to
  // look for the deeplink in the conversionData dictionary. Ask your producer for the specific field
  // you should be looking for in this dictionary.
  // An example payload for a basic Facebook link could look like:
  // conversionData = {
  //    "af_deeplink": true,
  //    "host": "facebook",
  //    "media_source": "Social Facebook",
  //    "path": "/reward/coins/1000/abc123",
  //    "scheme": "bfgsample",
  //    "shortlink": "dlfbpost"
  // }
  // For this example, you might be interested in the 'path' field of the dictionary, where you could extract
  // a promo code or other meaningful information for your game.
  NSString *hostString = conversionData[@"host"];
  NSString *pathString = conversionData[@"path"];
  if (conversionData && conversionData.count > 0 && [hostString isEqualToString:@"facebook"] && pathString.length)
  {
      BFGUIKitExampleLog(@"The UA tracking provider provided additional conversion data for the universal link and/or deep link: %@", conversionData);
  }
}

Add URI scheme to your plist

<key>CFBundleURLSchemes</key>
<array>
  <string>bfgsample</string>
</array>

Add support for Universal Links

Universal Links is a deep linking protocol created by Apple and was introduced in iOS versions 9+. Universal Links enables app developers to create a two-way association between their mobile app and website. The advantage to supporting universal links is that tapping on them in an email or a banner ad can directly open your app if it is installed, instead of first routing the user through Safari or another browser. Universal links are similar to regular deep links in that they can launch your app and deliver a payload, but they have a slightly different structure inside the app code.

A universal link can be configured for any of four scenarios:

To take the user to the App Store.
To deep link to the Apple App Store for a download. In this scenario, when a user does not have your app installed, they will be taken to the App Store and, if they choose to install it, the universal link payload will be delivered, for example, as a deferred deep link or a referral link.
If the app is installed and the link is a deep link, it will take the user directly to the app and then deep link them to the given location, for example, if you want the user to access a bonus level.
If the app is installed and the link is a referral link, it will open the app.

Your Big Fish producer will enable universal links through the AppsFlyer Developer Portal. You will be given a referral link similar to the one below, but it will be specific to your game.

//bfgsdk.onelink.me/yryN/4f196e66

To use universal links, you need to add another pass-through call to bfgManager in your app delegate:

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
  [bfgManager applicationContinueUserActivity:userActivity restorationHandler:restorationHandler];
  // Do any special processing of the universal link here
  return YES;
}

Deep Linking

What is Deep Linking?​

Receiving Deep Link Notifications (Unity only)​

Setting up Deep Links​

Unity SDK (Android Targets)​

Unity SDK (iOS Targets)​

Native Android SDK​

Native iOS SDK​