Using Referral Codes

Having finished with your Integration for Android or iOS, you may now be looking at implementing a Referral Campaign driven by both: Code & Link.

AppVirality supports both referral code and referral link to attribute Friend/Referrer.

Referral program can be configured with 3 different attribution settings.

Link + Referral Code (default)
Only Referral Link
Only Referral Code

As mentioned above, the default settings employ Link + Code based attribution for your Referral program.

To build a context, you may take a deeper dive into what each of these attribution settings implies

LINK + REFERRAL CODE (default)

When you set attribution setting to “Link+Referral Code” it will enable users to get attributed and rewarded based on both: Referral Link and Referral Code.

In this case attribution may happen itself right after launching the app and hence submitting referral code after that will do nothing, so before prompting the user to enter referral code use appVirality.isAttributionConfirmed() to know the attribution status. If attribution has already been confirmed do not show the option to enter referral code, also don’t submit the referral code to AppVirality.

Here again three different cases come into play:

User may install the App by clicking on referral link in same network/IP
User may install the App by clicking on referral link from different network/IP
User may install the App directly and enter his friend’s referral code.

NOTE: Rewards will be processed in all the cases.

ONLY REFERRAL LINK

Read up on Device Fingerprinting to get a full understanding of how this sort of installation attribution works.

This method is considered to be 99% accurate. AppVirality improves this accuracy by taking advantage of Google Install Referrer on Android and SFSafariViewController cookie support on iOS.

AppVirality indexes a Click ID in Share URL, which is returned back by the Google Install Referrer on App’s first launch.

Example:

Referrer invites his friend by sharing his personal referral link
Friend Clicks on the referral link, which redirects to Play Store or Appstore based on Friend’s device OS.
Friend installs the App and launches for the first time.
AppVirality uses device finger printing and Google Install Referrer(for Android) or SFSafariViewController( for iOS) to attribute the friend’s install to the genuine referrer, thereafter processing the rewards based on the reward rules.

NOTE: Attribution and Reward processing will happen only based on Link attribution.

ONLY REFERRAL CODE

AppVirality supports referral code, wherein a user installs the App and enters their friend’s referral code during signup. Even though attribution method may be set to “Only Referral Code”, there are two possibilities.

Friend may directly install the App and enter the referral code
Friend can click on referral link and install the App

AppVirality uses generic device finger printing technology to attribute the users primarily if friend installs the App by clicking on referral link. But rewards will not be processed.

Once user enters his friend’s referral code, AppVirality verifies previously performed attribution(with device finger printing and deep link) and makes changes to the attribution based on entered referral code, followed by processing of the rewards.
Rewards will be processed based on reward rules and conversion events declared in the campaign.

NOTE: Rewards will not be processed until user enters his friend’s referral code.

Use Email ID of users to Initialize the SDK, everytime!

It is highly recommended that you use the User’s email ID for initializing the SDK every time. This will ensure that the user’s Referral Code & Invitation Link remains the same, regardless of the device he logs into.

Auto Populate Referral Code

Prefetching and populating the Referral Code from the invite received by the Friend, on his device during 1st App Launch

To elaborate this, when a new user acts on the Invite Link and installs the app - it is a convention nowadays to pre-fetch and populate the Referral Code of the Referrer in the Friend’s device during the onboarding, ideally during the Welcome Screen.

Unlike as shown in the image…

This can be done after the Integration is finished, in the following manner.

Instead of user entering his friend’s referral code manually, you can auto populate the same. So immediately on the 1st app launch of the app on the friend’s device, it is expected that you have initialized the SDK.

Follow up the initialization with calling out the getReferrerRefCode() method to get the Referrer’s Referral code. That should get you the code to populate on the Welcome Screen

ANDROID
iOS

  String referralCode = appVirality.getReferrerRefCode();

NOTE: If you are taking advantage of Google Install Referrer, you need not wait for AppVirality SDK Initialization, to get the Referral code. You can directly call the above method to populate the referral code during user signup

Referrer Code is available in Init callback.i.e. in referrerDetails.

  [AppVirality initWithApiKey:@"YOUR-APP-KEY" OnCompletion:^(NSDictionary *referrerDetails,NSError*error) {
            NSLog(@"User has Referrer %@", referrerDetails);
        }];

Sending back Referral Code to AppVirality

Once, as stated above, the Referral Code is entered, you would need to feed it back to AppVirality to close the loop on the attribution process. If not done, no rewards would be processed for the entire activity.

This will be most useful if the user is not attributed using Deep link(due to network changes/IP changes) or if user installs the App directly without clicking on referral link.

You need to use this method only if the attribution has not happened already using the Referral Link and user has to enter the referrer’s referral code to get attributed to him.

ANDROID
iOS

if (!appVirality.isAttributionConfirmed()) {
    appVirality.submitReferralCode(refCode, new AppVirality.SubmitReferralCodeListener() {
        @Override
        public void onResponse(boolean isSuccess, JSONObject responseData, String errorMsg) {
            String message = isSuccess ? "Referral Code applied Successfully" : (errorMsg != null ? errorMsg : "Failed to apply referral code");
            Toast.makeText(getApplicationContext(), message, Toast.LENGTH_SHORT).show();
        }
    });
}

NOTE: If you have opted for Only Referral Code attribution setting, please make sure to execute the above method before sending any conversion events(i.e. Signup,Transaction..etc)

[AppVirality submitReferralCode:self.txtReferrerCode.text completion:^(BOOL success, NSError *error) {
            if (success) {
                NSLog(@"Referral Code applied Successfully");
                }
            else{
                NSLog(@"Invalid Referral Code");
            }

}
        ];

Get User Referral Code - to invite friends

AppVirality generates user referral code as soon as user requests for a campaign.

The referral code depends on the campaign that user interested to participate. Referral code is nothing but the campaign participation ID. This gets generated when AppVirality receives a request for campaign, from a user for the first time.

This is expected to be triggered when the User taps on the ‘Invite & Earn’ button (or something likewise), from your app menu

We can get the referral code with the help of following code block

ANDROID
iOS

appVirality.getCampaigns(null, new AppVirality.CampaignDetailsListener() {
    @Override
    public void onGetCampaignDetails(ArrayList<CampaignDetail> campaignDetails, boolean refreshImages, String errorMsg) {
        CampaignDetail womCampaignDetail = appVirality.getCampaignDetail(Constants.GrowthHackType.Word_of_Mouth, campaignDetails);
        if (refreshImages) {
            // Refresh Word Of Mouth campaign images
        }
        if (womCampaignDetail != null) {
            String myReferralCode = womCampaignDetail.referralCode;
        }
    }
});

[AppVirality showGrowthHack:growthHack completion:^(NSDictionary *campaignDetails,NSError*error) {
NSString * myReferralCode = [campaignDetails valueForKey:@"shortcode"];
}];