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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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

            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();
    }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
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}")
    }
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[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

        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);
}];

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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)")
        })

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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

            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)
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
final ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// final ReferralUsersQuery query = ReferralUsersQuery.usersForEvent("event");
GetSocial.getReferredUsers(query, new Callback<List<ReferralUser>>() {
    @Override
    public void onSuccess(List<ReferralUser> result) {
        // process referred users
    }

    @Override
    public void onFailure(GetSocialException exception) {
        // handle error
    }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// val query = ReferralUsersQuery.usersForEvent("event")
GetSocial.getReferredUsers(query, object : Callback<List<ReferralUser>> {
    override fun onSuccess(result: List<ReferralUser>) {
        // process referred users
    }

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

1
2
3
4
5
6
7
8
GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery allUsers];
// to return users only for a specific event:
// GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery usersForEvent:@"event";
[GetSocial referredUsersWithQuery:query success:^(NSArray<GetSocialReferralUser *> *_Nonnull referrerUsers) {
    // process referred users
} failure:^(NSError *_Nonnull error) {
    // handle error
}];

1
2
3
4
5
6
7
8
9
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
})

1
2
3
4
5
6
7
8
9
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
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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.

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 install and eventDate value is after reward check date, you can give the reward.
    • If you’re doing the reward based on the number of referred users, you probably want to check reinstall attribute in eventData, which means that it’s not the first install on this device.
    • If you need absolutely guarantee to install is 100% genuine, you want to use installSuspicious 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
final String referrerId = ... // referrer user id
final String event = ... // event
Map<String, String> customData = ... // any custom data

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

    @Override
    public void onFailure(GetSocialException exception) {
        // handle error
    }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val referrerId = ... // referrer user id
val event = ... // event
val customData: Map<String, String> = ... // any custom data
GetSocial.setReferrer(referrerId, event, customData, object: CompletionCallback {
    override fun onSuccess() {
        // referrer information is set
    }

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

1
2
3
4
5
6
7
8
9
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
}];

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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
    }
)

1
2
3
4
5
6
7
8
9
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
});

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
final ReferralUsersQuery query = ReferralUsersQuery.allUsers();
// to return users only for a specific event:
// final ReferralUsersQuery query = ReferralUsersQuery.usersForEvent("event");
GetSocial.getReferrerUsers(query, new Callback<List<ReferralUser>>() {
    @Override
    public void onSuccess(List<ReferralUser> result) {
        // process referrer users
    }

    @Override
    public void onFailure(GetSocialException exception) {
        // handle error
    }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val query = ReferralUsersQuery.allUsers()
// to return users only for a specific event:
// val query = ReferralUsersQuery.usersForEvent("event")
GetSocial.getReferrerUsers(query, object : Callback<List<ReferralUser>> {
    override fun onSuccess(result: List<ReferralUser>) {
        // process referrer users
    }

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

1
2
3
4
5
6
7
8
GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery allUsers];
// to return users only for a specific event:
// GetSocialReferralUsersQuery* query = [GetSocialReferralUsersQuery usersForEvent:@"event";
[GetSocial referrerUsersWithQuery:query success:^(NSArray<GetSocialReferralUser *> *_Nonnull referrerUsers) {
    // process referrer users
} failure:^(NSError *_Nonnull error) {
    // handle error
}];

1
2
3
4
5
6
7
8
9
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
})

1
2
3
4
5
6
7
8
9
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
});

1
Feature is not supported in current version of the SDK.

Give us your feedback! Was this article helpful?

😀 🙁