Skip to content

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 retrieve 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.

The code below show how to do it:

```java tab=”Java”
GetSocial.getReferralData(new FetchReferralDataCallback() {
@Override
public void onSuccess(@Nullable ReferralData referralData) {
if(referralData != null) {
String navigationPath = (String) referralData.getLinkParams().get(“$custom_path”); // predefined key
String customValue1 = (String) referralData.getLinkParams().get(“custom_key_1”); // custom key
boolean isGuaranteedMatch = referralData.isGuaranteedMatch(); // added metadata

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
        Toast.makeText(MainActivity.this, "App started with referral data: " + referralData, Toast.LENGTH_LONG).show();
    } else {
        Toast.makeText(MainActivity.this, "No referral data found", Toast.LENGTH_LONG).show();
    }
}

@Override
public void onFailure(GetSocialException error) {
    Toast.makeText(MainActivity.this, "Failed to retrieve referral data, error: " + error, Toast.LENGTH_LONG).show();
}

});
kotlin tab=”Kotlin”
GetSocial.getReferralData(object : FetchReferralDataCallback {
override fun onSuccess(referralData: ReferralData?) {
if (referralData != null) {
val navigationPath = referralData.linkParams[“\$custom_path”] // predefined key
val customValue1 = referralData.linkParams[“custom_key_1”] // custom key
val isGuaranteedMatch = referralData.isGuaranteedMatch // added metadata

println(“App started with referral data: ${referralData}”)
} else {
println(“No referral data found”)
}
}

override fun onFailure(exception: GetSocialException) {
println(“Failed to retrieve referral data, error: ${exception.message}”)
}
})
```

```objc tab=”Objective-C”
[GetSocial referralDataWithSuccess:^(GetSocialReferralData * _Nullable referralData) {
if (referralData != nil) {
NSString * navigationPath = [referralData linkParams][@”$custom_path”]; // predefined key
NSString * customValue1 = [referralData linkParams][@”custom_key_1”]; // custom key
BOOL isGuranteedMatch = [referralData isGuaranteedMatch]; // added metadata

1
2
3
4
    NSLog(@"App started with referral data: %@", referralData);
} else {
    NSLog(@"No referral data found");
}

} failure:^(NSError * _Nonnull error) {
NSLog(@”Failed to retrieve referral data, error: %@”, error.description);
}];
swift tab=”Swift”
GetSocial.referralData(success: { referralData in
guard let referralData = referralData else {
print(“No referral data found”)
return
}
let navigationPath = referralData.linkParams[“$custom_path”] // 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)”)
}, failure: { error in
print(“Failed to retrieve referral data, error: (error)”)
})
```

```c# tab=”Unity”
GetSocial.GetReferralData(
onSuccess: (referralData) => {
if(referralData != null) {
string navigationPath = (string) referralData.LinkParams[“$custom_path”]; // predefined key
string customValue1 = (string) referralData.LinkParams[“custom_key_1”]; // custom key
bool isGuranteedMatch = referralData.IsGuaranteedMatch; // added metadata

1
2
3
4
5
6
        Debug.Log("App started with referral data: " + referralData);
    } else {
        Debug.Log("No referral data found");
    }
},
onFailure: (error) => Debug.LogError("Failed to retrieve referral data, error: " + error.Message)

);
javascript tab=”React Native”
GetSocial.getReferralData().then((referralData) => {
if (referralData == null) {
console.log(‘Referral data’, ‘No referral data found.’);
} else {
const navigationPath = referralData.linkParams[‘$custom_path’]; // predefined key
const customValue1 = referralData.linkParams[‘custom_key_1’]; // custom key
const isGuaranteedMatch = referralData.isGuaranteedMatch; // added metadata

console.log(‘Referral data’, ‘App started with referral data: ‘ + JSON.stringify(referralData));
}
}, (errorMessage) => {
console.log(‘Failed to retrieve referral data’, errorMessage);
});
```

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.

Retrieve Referred Users

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

```java tab=”Java”
final ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// final ReferralUsersQuery query = ReferralUsersQuery.usersForEvent(“event”);
GetSocial.getReferredUsers(query, new Callback>() {
@Override
public void onSuccess(List result) {
// process referred users
}

1
2
3
4
@Override
public void onFailure(GetSocialException exception) {
    // handle error
}

});
kotlin tab=”Kotlin”
val query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// val query = ReferralUsersQuery.usersForEvent(“event”)
GetSocial.getReferredUsers(query, object : Callback> {
override fun onSuccess(result: List) {
// process referred users
}

override fun onFailure(exception: GetSocialException) {
// handle error
}
})
```

```objc tab=”Objective-C”
GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery allUsers];
// to return users only for a specific event:
// GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery usersForEvent:@”event”;
[GetSocial referredUsersWithQuery:query success:^(NSArray *_Nonnull referrerUsers) {
// process referred users
} failure:^(NSError *_Nonnull error) {
// handle error
}];

```swift tab="Swift"
let query = GetSocialReferralUsersQuery.allUsers()
// to return users only for a specific event:
// let query = GetSocialReferralUsersQuery.usersForEvent("event")
let query = GetSocialReferralUsersQuery.allUsers()
GetSocial.referredUsers(with: query, success: { referralUsers in
    // process referred users
}, failure: { error in
    // handle error
})

```c# tab=”Unity”
var query = ReferralUsersQuery.AllUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.UsersForEvent(“event”);
GetSocial.GetReferredUsers(query, referralUsers => {
// process referred users
}, error =>
{
// handle error
});

```javascript tab="React Native"
GetSocial.getReferredUsers().then((referredUsers) => {
if (referredUsers.length > 0) {
    // current user invited others to the app
    console.log('Referred Users', JSON.stringify(referredUsers));
} else {
    console.log('Referred Users', 'No referred users.');
}
}, (errorMessage) => {
    console.log('Failed to retrieve ReferredUsers, error: ', errorMessage);
});

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

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 true 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 Users

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

```java tab=”Java”
final String referrerId = … // referrer user id
final String event = … // event
Map customData = … // any custom data

GetSocial.setReferrer(referrerId, event, customData, new CompletionCallback() {
@Override
public void onSuccess() {
// referrer information is set
}

1
2
3
4
@Override
public void onFailure(GetSocialException exception) {
    // handle error
}

});
kotlin tab=”Kotlin”
val referrerId = … // referrer user id
val event = … // event
val customData: Map = … // any custom data
GetSocial.setReferrer(referrerId, event, customData, object: CompletionCallback {
override fun onSuccess() {
// referrer information is set
}

override fun onFailure(exception: GetSocialException) {
// handle error
}
})
```

```objc tab=”Objective-C”
NSString* referrerId = … // referrer user id
NSString* event = … // event
NSDictionary* customData = … // any custom data

[GetSocial setReferrerWithId:referrerId event:event customData:customData success:^() {
// referrer information is set
} failure:^(NSError * _Nonnull error) {
// handle error
}];

```swift tab="Swift"
let referredId = ... // referrer user id
let event = ... // event
let customData = ... // any custom data

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

```c# tab=”Unity”
var referrerId = … // referrer user id
var event = … // event
var customData = … // any custom data

GetSocial.SetReferrer(referrerId, event, customData, () => {
// referrer information is set
}, (error) => {
// handle error
});

```javascript tab="React Native"
Feature is not supported in current version of the SDK.

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.

```java tab=”Java”
final ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// final ReferralUsersQuery query = ReferralUsersQuery.usersForEvent(“event”);
GetSocial.getReferrerUsers(query, new Callback>() {
@Override
public void onSuccess(List result) {
// process referrer users
}

1
2
3
4
@Override
public void onFailure(GetSocialException exception) {
    // handle error
}

});
kotlin tab=”Kotlin”
val query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// val query = ReferralUsersQuery.usersForEvent(“event”)
GetSocial.getReferrerUsers(query, object : Callback> {
override fun onSuccess(result: List) {
// process referrer users
}

override fun onFailure(exception: GetSocialException) {
// handle error
}
})
```

```objc tab=”Objective-C”
GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery allUsers];
// to return users only for a specific event:
// GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery usersForEvent:@”event”;
[GetSocial referrerUsersWithQuery:query success:^(NSArray *_Nonnull referrerUsers) {
// process referrer users
} failure:^(NSError *_Nonnull error) {
// handle error
}];

```swift tab="Swift"
let query = GetSocialReferralUsersQuery.allUsers()
// to return users only for a specific event:
// let query = GetSocialReferralUsersQuery.usersForEvent("event")
let query = GetSocialReferralUsersQuery.allUsers()
GetSocial.referrerUsers(with: query, success: { referralUsers in
    // process referrer users
}, failure: { error in
    // handle error
})

```c# tab=”Unity”
var query = ReferralUsersQuery.AllUsers();
// to return users only for a specific event:
// var query = ReferralUsersQuery.UsersForEvent(“event”);
GetSocial.GetReferrerUsers(query, referralUsers => {
// process referrer users
}, error =>
{
// handle error
});

```javascript tab="React Native"
Feature is not supported in current version of the SDK.

Give us your feedback! Was this article helpful?

😀 🙁