SaaSquatch Help Center

SaaSquatch integrates with AppsFlyer to provide additional attribution, personalization, and analytics for mobile app referral programs by using AppsFlyer's OneLinks.

This Quickstart Guide outlines the core steps involved in setting up your mobile app to work with AppsFlyer and your referral program.

🔗 Configuring AppsFlyer for your App

An AppsFlyer account is needed in order to integrate the AppsFlyer functionality into your SaaSquatch project.

🔗 Creating an account

AppsFlyer offers a free plan for app owners with the option to upgrade for added features. If you don’t have an AppsFlyer account yet, you can sign up for one for free through AppsFlyer. All that is required is a valid email account.

🔗 Configuring AppsFlyer

AppsFlyer Create OneLink

After adding your app to AppsFlyer, go to your dashboard and select the OneLink Custom Links heading on the left sidebar.

Custom AppsFlyer OneLink

Create a OneLink Template for your application and select to add a custom link. Configure your custom link and the fields for mobile redirection and deep linking under the redirecting & deep linking tab. Be sure to leave the field for when the link is clicked on desktop empty. SaaSquatch will fill in the af_web_dp field dynamically so that the desktop landing page can be configured from within the SaaSquatch portal.


🔗 Updating your Mobile App

To access the AppsFlyer deep linking data from within your mobile application you will need to install the AppsFlyer SDK. The AppsFlyer documentation contains all the steps required to get their SDK setup on your application.

Once set up, you can retrieve the deep link data from AppsFlyer. This data contains information about the referral and can be used to attribute the referral and customize the signup experience for new users.

Here is an example of the SaaSquatch data that will be appended to the AppsFlyer onelink:

{
    "af_web_dp": "http://myReferralLandingPage.com",
    "utm_source": "invite",
    "utm_medium": "link",
    "utm_campaign: "saasquatch",
    "rsCode": "REFERRALCODE,
    "rsShareMedium": "UNKNOWN",
    "rsEngagementMedium": "UNKNOWN",
    "_saasquatch":         "eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZXN0XzEyMzQ1NjdfQ09ERSI6eyJjb2RlcyI6eyJyZWZlcnJhbCI6IlJFRkVSUkFMQ09ERSJ9LCJjb2Rlc0V4cCI6eyJSRUZFUlJBTENPREUiOjE2Mjk1ODIxOTl9LCJsaW5rcyI6eyJyZWZlcnJhbCI6Imh0dHBzOi8vc3NxdC5jby9temFBMjIifSwibGlua3NFeHAiOnsiaHR0cHM6Ly9zc3F0LmNvL216YUEyMiI6MTYyOTU4MjE5OX19fX0="
}

AppsFlyer may add other parameters depending on how your OneLink is configured. The most important parameter from the SaaSquatch side is _saasquatch which contains the referral code and sharelink used for the referral and are needed for attributing the referral. For more detail on data fields and behaviour, check out our AppsFlyer Integration Reference.


🔗 Deep linking on iOS

Prior to implementing deep linking in your mobile application, be sure to follow the AppsFlyer IOS SDK integration documentation to initialize and implement the SDK in your application and read their IOS developer documentation for general information on setting up deep linking within your application. We also recommend following AppsFlyer’s four part guide outlining the steps to getting deep linking set up on your mobile application.

🔗 Configuring and Initializing the SDK

In AppDelegate.swift, import AppsFlyerLib and add the AppsFlyerTrackerDelegate to the class declaration.

import AppsFlyerLib
class AppDelegate: UIResponder, UIApplicationDelegate, AppsFlyerTrackerDelegate {
   // your code here
}

Use the code in the AppsFlyer docs to initialize the SDK with your app ID taken from iTunes Connect and your AppsFlyer dev key. The app ID is digits only, without the "id" prefix. The code supports iOS 13 and scene delegate. You can use it even if the app doesn't support scene delegate.

In order to support deep linking, add code found in the AppsFlyer docs to SceneDelegate for every scene your app supports deep linking into. For more information visit AppsFlyer’s IOS SDK Integration documentation.


🔗 Deep Linking on Android

Prior to implementing deep linking in your mobile application, be sure to follow the AppsFlyer Android SDK integration documentation to initialize and implement the SDK in your application and read their Andriod developer documentation for general information on setting up deep linking within your application. We recommend going through AppsFlyer’s four part guide outlining the steps to getting deep linking set up on your mobile application.

🔗 Configuring and Initializing the SDK

To initialize the AppsFlyer Andriod SDK, you must do three things. Firstly, inside the app's global class, import the following libraries

import android.app.Application;
import android.util.Log;
import com.appsflyer.AppsFlyerLib;
import com.appsflyer.AppsFlyerConversionListener;
import java.util.Map;

Secondly, inside the global class, assign your dev key to a variable, preferably named AF_DEV_KEY.

public class AFApplication extends Application {
    private static final String AF_DEV_KEY = "MY_DEV_KEY";

    //...

}

Thirdly, in the AndroidManifest.xml file, inside the application tag, add the following line, replacing APP.PACKAGE.NAME with the app's package name and AFApplication with the name that you set for the app's global class.

android:name="APP.PACKAGE.NAME.AFApplication"

For more information visit AppsFlyer’s Andriod SDK Integration documentation.


🔗 Getting Deep Link Data

The AppsFlyer SDK returns the deep linked conversion data through two dedicated methods.

  • onConversionDataSuccess is used for User Acquisition (UA) and re-attribution conversions, holding the full cached attribution data.
  • onAppOpenAttribution is used for re-engagement conversions as it uses the attributionData map to dispatch other activities in the app and pass relevant data.

To connect your referrals and optimize the landing experience for both new and existing users you will need to implement the logic for both direct and deferred deep linking. For more detail visit the AppsFlyer documentation outlining how to get conversion data on IOS and how to get conversion data on Android.

🔗 Swift Sample Code for direct deep linking:

When a OneLink is clicked and the user has the app installed on their device, the onAppOpenAttribution method is called by the AppsFlyer SDK. This is referred to as a retargeting re-engagement.

The deep link calls the onAppOpenAttribution method in the AppDelegate. The parameters in the method input are used to implement the specific user experience when the application is opened.

func onAppOpenAttribution(_ attributionData: [AnyHashable: Any]) { 
    //Handle Deep Link Data 
    print("onAppOpenAttribution data:") 
    for (key, value) in attributionData { 
        print(key, ":",value) 
    } 
    walkToSceneWithParams(params: attributionData)
} 

// User logic 
fileprivate func walkToSceneWithParams(params: [AnyHashable:Any]) {
    let storyBoard: UIStoryboard = UIStoryboard(name: "Main", bundle: nil)      
    UIApplication.shared.windows.first?.rootViewController?.dismiss(animated: true, completion: nil)

    var referralData = ""

    if let cookie = params["_saasquatch"] as? String { 
        referralData = cookie
    }

/* insert custom logic here to handle user landing experience in app. Depending on your referral flow and signup process, make sure you handle/store the SaaSquatch attribution data in your application so that on signup you can complete the attribution. 
*/

}

func onAppOpenAttributionFailure(_ error: Error) {  
    print("\(error)") 
}

See AppsFlyer Developer Documentation for direct deep linking on iOS and Android.

🔗 Swift Sample Code for deferred deep linking:

For deferred deep linking, the onConversionDataSuccess method input must be planned and the input decided in the previous section (for deep linking) is made relevant for the first time the app is launched.

When the app is opened for the first time, the onConversionDataSuccess method is triggered in the main activity. The parameters in the method input are used to implement the specific user experience when the app is first launched.

// Handle Organic/Non-organic installation 
func onConversionDataSuccess(_ data: [AnyHashable: Any]) { 
    print("onConversionDataSuccess data:") 
    for (key, value) in data { 
        print(key, ":", value) 
    } 

    if let status = data["af_status"] as? String { 
        if (status == "Non-organic") { 
            if let sourceID = data["media_source"], 
                let campaign = data["campaign"] { 
                print("This is a Non-Organic install. Media source: \(sourceID) Campaign: \        (campaign)") 
            } 
        } else { 
            print("This is an organic install.") 
        } 
        if let is_first_launch = data["is_first_launch"] as? Bool, 
            is_first_launch { 
            print("First Launch") 
            if let _saasquatch = data["_saasquatch"] 
            { 
                // The key '_saasquatch' exists only in OneLink originated installs from a SaaSquatch program
                print("deferred deep-linking params: \(_saasquatch)")
                walkToSceneWithParams(params: data)            } 
            else { 
                print("Install from a non-owned media") 
            } 
        } else { 
            print("Not First Launch") 
        } 
    } 
}

func onConversionDataFail(_ error: Error) {  
    print("\(error)") 
}

See AppsFlyer Developer Documentation for deferred deep linking on iOS and Android.


🔗 Connecting AppsFlyer to your SaaSquatch Account

Live vs. Test

We recommend testing any new integration on your SaaSquatch Test Tenant before launching it on your Live Tenant. Since AppsFlyer does not offer a test environment, we suggest creating a test custom link first then following the steps below to connect the integration on your SaaSquatch Test Tenant.

Once you have tested the integration thoroughly and are happy with the configuration, you can make a new custom link in AppsFlyer and repeat the setup steps for your Live Tenant.

AppsFlyer OneLink

  1. Retrieve the short URL for your desired AppsFlyer link, located on the OneLink Custom Links tab of your AppsFlyer Dashboard

  2. Log into your Saasquatch portal and go the Settings > Integrations > AppsFlyer Integration

  3. Open up the AppsFlyer integration settings using the chevron and click Enable AppsFlyer

  4. Paste your short URL into the AppsFlyer base attribution link field and click Save

Please note that the URL you provide will be used for all of your SaaSquatch programs.


🔗 Next Steps

With access to the AppsFlyer deep linking data, you can now know when a mobile user was referred through a SaaSquatch program. Additionally you can use this information to enrich the mobile landing experience for your referred users.

Include the _saasquatch value in the cookies field of a User Upsert to attribute the referral when you identify the user to SaaSquatch. This can be done using our REST API or Graphql API and upserting a user as shown below:

{   
    "id": "219065", 
    "accountId": "accc9065", 
    "firstName": "Bob", 
    "lastName": "Testerson", 
    "email": "bob@example.com", 
    "referable": true, 
    "referralCode": "BOBTESTERSON", 
    "locale": "en_US", 
    "cookies":     
"eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZXN0XzEyMzQ1NjdfQ09ERSI6eyJjb2RlcyI6eyJyZWZlcnJhbCI6IlJFRkVSUkFMQ09ERSJ9LCJjb2Rlc0V4cCI6eyJSRUZFUlJBTENPREUiOjE2Mjk1ODIxOTl9LCJsaW5rcyI6eyJyZWZlcnJhbCI6Imh0dHBzOi8vc3NxdC5jby9temFBMjIifSwibGlua3NFeHAiOnsiaHR0cHM6Ly9zc3F0LmNvL216YUEyMiI6MTYyOTU4MjE5OX19fX0="
}