Referral Data and Users

Retrieve Referral Data

Returned referral data contains:

1. Predefined link params and custom key-value pairs added during link creation, or as URL query parameter overrides.
2. Metadata added by GetSocial, e.g., channel, referrer user, whether we guarantee attribution, etc.

For a full list of available properties check the Smart Link params reference and API Reference.

You can set a listener to be invoked with referral data attached to the Smart Link when:

• The app is launched for a first time after being installed by clicking on the GetSocial Smart Link.
• The app was opened by clicking on the GetSocial Smart Link.

Referral data on Web SDK

The Web SDK doesn’t provide a way to register a listener but it does provide referral data as part of the response of the authenticate method or when the SDK is initialized if a previous valid session was found. More info

The code below show how to do it:

Android

Invites.setReferralDataListener { referralData: ReferralData ->
    val navigationPath = referralData.linkParams["\$token"]  // predefined key
    val customValue1 = referralData.linkParams["custom_key_1"] // custom key
    val isGuaranteedMatch = referralData.isGuaranteedMatch // added metadata

    Log.d("Invites", "App started with referral data: ${referralData}")
}

iOS

Invites.setOnReferralDataReceivedListener { referralData in
    let navigationPath = referralData.linkParams["$token"] // predefined key
    let customValue1 = referralData.linkParams["custom_key_1"] // custom key
    let isGuranteedMatch: Bool = referralData.isGuaranteedMatch // added metadata

    print("App started with referral data: \(referralData)")
}

Unity

Invites.SetOnReferralDataReceivedListener((referralData) => {
    var navigationPath = referralData.LinkParams["$token"]; // predefined key
    var customValue1 = referralData.LinkParams["custom_key_1"]; // custom key
    var isGuaranteedMatch = referralData.IsGuaranteedMatch; // added metadata

    Debug.Log("App started with referral data: " + referralData);
});

Flutter

Invites.setOnReferralDataReceivedListener((ReferralData referralData) => {
    var navigationPath = referralData.linkParams['$token'], // predefined key
    var customValue1 = referralData.linkParams['custom_key_1'], // custom key
    var isGuaranteedMatch = referralData.isGuaranteedMatch, // added metadata

    print('App started with referral data: $referralData')
});

React Native

Invites.setOnReferralDataReceivedListener((referralData) => {
    const navigationPath = referralData.linkParams['$token']; // predefined key
    const customValue1 = referralData.linkParams['custom_key_1']; // custom key
    const isGuaranteedMatch = referralData.isGuaranteedMatch; // added metadata

    console.log('App started with referral data: ' + referralData);
});

Whitelist Test Devices

To get the install attribution on every install you have to whitelist your testing devices on the GetSocial Dashboard.
For more information check Whitelist Test Devices.

Test in Unity Editor

If you want to test your referral data listener implementation, you can trigger the listener by clicking on GetSocial -> Helper Methods -> Trigger Referral Data Listener.
If you want to change the referral data which your listener is invoked with, modify the TriggerReferralDataListener method in Assets/GetSocial/Editor/GetSocialSettingsEditor.cs file.

Retrieve Referred Users

Using GetSocial data API you can retrieve the list of users who installed application from the invitations sent by current user:

Android

val query = ReferralUsersQuery.allUsers()
// or to get users for a specific event:
val query = ReferralUsersQuery.usersForEvent("event")
val pagingQuery = PagingQuery(query)

Invites.getReferredUsers(pagingQuery, { result: PagingResult<ReferralUser> ->
    val users = result.entries
    Log.d("Invites", "Referred users: $users")
}, { error: GetSocialError ->
    Log.d("Invites", "Failed to get referred users: $error")
})

iOS

let query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// let query = ReferralUsersQuery.usersForEvent("event")
let pagingQuery = ReferralUsersPagingQuery(query)
Invites.referredUsers(pagingQuery, success: { response in
    // process referred users
    let referredUsers = response.users
}, failure: { error in
    // handle error
})

Unity

var query = ReferralUsersQuery.AllUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.UsersForEvent("event");
var pagingQuery = new PagingQuery<ReferralUsersQuery>(query);

Invites.GetReferredUsers(pagingQuery,
    (result) => {
        // process referred users
        var referredUsers = result.Entries;
    },
    (error) => {
        // handle error
    });

Flutter

ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.usersForEvent('event');
Invites.getReferredUsers(new PagingQuery(query))
    .then((value) => {
        var users = value.entries,
        /* process referred users */
    });

React Native

const query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.usersForEvent('event');
Invites.getReferredUsers(new PagingQuery(query))
    .then((value) => {
        const users = value.entries;
        /* process referred users */
    });

Web

const query = GetSocialSDK.ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = GetSocialSDK.ReferralUsersQuery.usersForEvent('event');
GetSocialSDK.Invites.getReferredUsers(query)
    .then((users) => {
        console.log('Users: ', users);
    }, (error) => {
    console.log('Failed to get referred users: ', error);
    });

ReferralUser object contains user details, including eventDate, which is the date when a referral event happened to the user in UTC.

This method uses the PagingQuery concept that is used across our SDK. Read more about this.

Event Data Keys

Key	Possible values	Meaning
$channel	e.g. whatsapp, sms and other invite channels	Channel used for invites or a Smart Link campaign.
$suspicious	true, false	false means install is 100% genuine, you may need it if rewarding with real money or other very sensible cases
$platform	iOS, Android, API, Web_Android, Web_iOS, Web_Desktop, Desktop_Windows, Desktop_Mac, Desktop_Linux, Other	Platform user used to install the app. Prefix Web_ means Web SDK, Desktop_ means Unity SDK on desktop platforms, Other is something we don’t support yet.

Check Unique Installs

This way, for example, you can reward your users for inviting other users:

1. Read last reward check date from private user properties.
2. If ReferralUser object event is app_install(or you queried users for app_install event only) and eventDate value is after reward check date, you can give the reward.
   • If you need absolutely guarantee to install is 100% genuine, you want to use $suspicious flag in eventData. It may be useful if you have any real money rewarding in your application.
3. Update reward check date to current date.

Set Referrer User

In addition to the default install referrer, you can set the referrer manually as well:

Android

val referrerId: UserId = ... // referrer user id
val event: String = ... // event
val customData: Map<String, String> = // any custom data
Invites.setReferrer(referrerId, event, customData, {
    Log.d("Invites", "Successfully set referrer")
}, { error: GetSocialError ->
    Log.d("Invites", "Failed to set referrer: $error")
})

iOS

let referredId: UserId = ... // referrer user id
let event = ... // event
let customData: [String: String] = ... // any custom data

Invites.setReferrer(referredId,
    event: event,
    customData: customData,
    success: {
        // referrer information is set
    }, failure: { error in
        // handle error
    }
)

Unity

UserId userId = ... // referrer user id
string referrerEvent = ... // event
var customData = new Dictionary<string, string>(); // any custom data

Invites.SetReferrer(userId, referrerEvent, customData,
    () => {
        // referrer information is set
    },
    (error) => {
        // handle error
    });

Flutter

UserId userId = ... // referrer user id
String referrerEvent = ... // event
Map<String, String> customData = Map();
Invites.setReferrer(userId, referrerEvent, customData).then(...);

React Native

const userId = ... // referrer user id
const referrerEvent = ... // event
const customData = new Map();
Invites.setReferrer(userId, referrerEvent, customData).then(...);

Web

const userId = GetSocialSDK.UserId.create('userId'); // referrer user id
const referrerEvent = 'event';
const customData = {};
GetSocialSDK.Invites.setReferrer(userId, referrerEvent, customData)
    .then(() => {
        console.log('User successfully set as referrer');
    }, (error) => {
    console.log('Failed to set referrer: ', error);
    });

Retrieve Referrer Users

You can retrieve the list of users who referred the current user to either install the application or take certain action in your application.

Android

val query = ReferralUsersQuery.allUsers()
// or to get users for a specific event:
val query = ReferralUsersQuery.usersForEvent("event")
val pagingQuery = PagingQuery(query)

Invites.getReferrerUsers(pagingQuery, { result: PagingResult<ReferralUser> ->
    val users = result.entries
    Log.d("Invites", "Referrer users: $users")
}, { error: GetSocialError ->
    Log.d("Invites", "Failed to get referrer users: $error")
})

iOS

let query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// let query = ReferralUsersQuery.usersForEvent("event")
let pagingQuery = ReferralUsersPagingQuery(query)
Invites.referrerUsers(pagingQuery, success: { response in
    // process referrer users
    let referrerUsers = response.users
}, failure: { error in
    // handle error
})

Unity

var query = ReferralUsersQuery.AllUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.UsersForEvent("event");
var pagingQuery = new PagingQuery<ReferralUsersQuery>(query);

Invites.GetReferrerUsers(pagingQuery,
    (result) => {
        // process referrer users
        var referrerUsers = result.Entries;
    },
    (error) => {
        // handle error
    });

Flutter

ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.usersForEvent('event');
Invites.getReferrerUsers(new PagingQuery(query))
    .then((value) => {
        var users = value.entries,
        /* process referrer users */
    });

React Native

const query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.usersForEvent('event');
Invites.getReferrerUsers(new PagingQuery(query))
    .then((value) => {
        const users = value.entries;
        /* process referrer users */
    });

Web

const query = GetSocialSDK.ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// var query = GetSocialSDK.ReferralUsersQuery.usersForEvent('event');
GetSocialSDK.Invites.getReferrerUsers(query)
    .then((users) => {
        console.log('Users: ', users);
    }, (error) => {
        console.log('Failed to get referrer users: ', error);
    });

This method uses the PagingQuery concept that is used across our SDK. Read more about this.

Give us your feedback! Was this article helpful?

😀 🙁