Referral programs

Overview

Branch allows you to reward users with credits, track those credits, and redeem them when appropriate. It is a unit-less currency available to your users without you having to build a system from scratch.

Guide

Prequisite

With every event that is recorded in Branch, we check automatically if that event is eligible for credits based on the rules that you configured, then deposit the credits if so. Reward rules can be based on both automatic events and custom events.

If you identify your users

Because we do not merge identities, you should set rewards on custom events and not use the events we automatically track (install and open), and do so only after you have identified a user using our identity methods. This will help avoid duplicate rewards and missing credits.

Awarding credits

Referral Fraud Protection

Branch tracks the hardware ID and IDFA of every device we detect, and ties these to our concept of a user identity. However, this means that you may run into issues if you test repeatedly with the same devices. When testing referral programs and reward rules, you should use debug mode.

To add a rule, go to the Dashboard Referrals page and click the Rules tab. Click the green "+ Add a new rule" button. Once there, you can select between two options:

Give reward

You can automatically give awards based on events taken by users.

Properties you can define:

  1. Who gets a reward
  2. How many credits the reward is
  3. Which bucket the credits go to
  4. Whether the reward occurs the first time or every time
  5. Which event triggers the reward

Example

Let's say you want to give 10 credits to each new user who signs up through a friend, and 5 credits to the friend who referred him or her. That can be done through a combination of two rules:

Rule 1: rewarding the referred user 10 credits

  1. Who gets a reward: "Referred acting users"
  2. How many credits the reward is: 10
  3. Which bucket the credits go to: default
  4. Whether the reward occurs the first time or every time: the first time
  5. Which event triggers the reward: install

image

Rule 2: rewarding the referring user 5 credits

  1. Who gets a reward: "Referring users"
  2. How many credits the reward is: 5
  3. Which bucket the credits go to: default
  4. Whether the reward occurs the first time or every time: the first time
  5. Which event triggers the reward: install

image

Viewing Credits

Once users have credits, they should be able to redeem them. Checking the balance involves loading the most recent balance from the server and then reading the balance. These can be two separate steps but for the sake of simplicity we have combined them into one example:

  • iOS - Swift

    Branch.getInstance().loadRewards { (changed, error) in
        if (error == nil) {
            let credits = Branch.getInstance().getCredits()
            print("credit: \(credits)")
        }
    }
    
  • iOS - Objective C

    [[Branch getInstance] loadRewardsWithCallback:^(BOOL changed, NSError *error) {
        if (!error) {
            NSLog(@"credit: %lu", [[Branch getInstance] getCredits]);
        }
    }];
    
  • Android

    Branch.getInstance(getApplicationContext()).loadRewards(new BranchReferralStateChangedListener() {
        @Override
        public void onStateChanged(boolean changed, Branch.BranchError error) {
            // changed boolean will indicate if the balance changed from what is currently in memory
    
            // will return the balance of the current user's credits
            int credits = branch.getCredits();
        }
    });
    

If you want to see the number of credits in a custom bucket you've specified, such as myBucket, then you can do the following:

  • iOS - Swift

    Branch.getInstance().loadRewards { (changed, error) in
        if (error == nil) {
            let creditsForBucket = Branch.getInstance().getCreditsForBucket()
            print("credit for bucket: \(creditsForBucket)")
        }
    }
    
  • iOS - Objective C

    [[Branch getInstance] loadRewardsWithCallback:^(BOOL changed, NSError *error) {
        if (!error) {
            NSString *bucket = @"myBucket";
            NSLog(@"credit for %@ bucket: %lu", bucket, [[Branch getInstance] getCreditsForBucket:bucket]);
        }
    }];
    
  • Android

    Branch.getInstance(getApplicationContext()).loadRewards(new BranchReferralStateChangedListener() {
        @Override
        public void onStateChanged(boolean changed, Branch.BranchError error) {
            // changed boolean will indicate if the balance changed from what is currently in memory
    
            if (error == null) {
                String bucket = "myBucket";
                Branch.getInstance(getApplicationContext()).getCreditsForBucket(bucket);
            }
        }
    });
    

Redeeming Credits

When users spend credits, you can make a simple call to redeem their credits.

  • iOS - Swift

    Branch.getInstance().redeemRewards(5, callback: {(success, error) in
        if success {
            print("Redeemed 5 credits!")
        }
        else {
            print("Failed to redeem credits: \(error)")
        }
    })
    
  • iOS - Objective C

    [[Branch getInstance] redeemRewards:5 callback:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"Redeemed 5 credits!");
        }
        else {
            NSLog(@"Failed to redeem credits: %@", error);
        }
    }];
    
  • Android

    Branch.getInstance(getApplicationContext()).redeemRewards(5);
    

If you want to redeem credits in a custom bucket you've specified, such as myBucket, then you can do the following:

  • iOS - Swift

    Branch.getInstance().redeemRewards(5, forBucket: "myBucket", callback: {(success, error) in
        if success {
            print("Redeemed 5 credits for myBucket!")
        }
        else {
            print("Failed to redeem credits: \(error)")
        }
    })
    
  • iOS - Objective C

    [[Branch getInstance] redeemRewards:5 forBucket:@"myBucket" callback:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"Redeemed 5 credits for myBucket!");
        }
        else {
            NSLog(@"Failed to redeem credits: %@", error);
        }
    }];
    
  • Android

    Branch.getInstance(getApplicationContext()).redeemRewards("myBucket", 5)
    

Example redemption flow

This is a simple three-part process:

  1. Ensure credits are loaded.
  2. Call the redeemRewards method and show a progress dialog.
  3. Show a completion dialog and reflect updates in balance.

  4. iOS - Swift

        Branch.getInstance().loadRewards(withCallback: {(_ changed: Bool, _ error: Error?) -> Void in
            if !(error && Branch.getInstance().getCredits() > 5) {
                Branch.getInstance().redeemRewards(5, callback: {(_ success: Bool, _ err: Error?) -> Void in
                    if err == nil {
                        var newBalance: Int = Branch.getInstance().getCredits()
                        var successMsg = "You redeemed 5 credits! You have \(Int(newBalance)) remaining."
                        UIAlertView(title: "Success", message: successMsg, delegate: nil, cancelButtonTitle: "OK", otherButtonTitles: "").show()
                    }
                })
            }
        })
    
  5. iOS - Objective C

    [[Branch getInstance] loadRewardsWithCallback:^(BOOL changed, NSError *error) {
        if (!error && [[Branch getInstance] getCredits] > 5) {
            [[Branch getInstance] redeemRewards:5 callback:^(BOOL success, NSError *err) {
                if (!err) {
                    NSInteger newBalance = [[Branch getInstance] getCredits];
                    NSString *successMsg = [NSString stringWithFormat:@"You redeemed 5 credits! You have %ld remaining.", (long)newBalance];
                    [[[UIAlertView alloc] initWithTitle:@"Success" message:successMsg delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil] show];
                }
            }];
        }
    }];
    
  6. Android

    Branch.getInstance().loadRewards(new BranchReferralStateChangedListener() {
        @Override
        public void onStateChanged(boolean changed, BranchError error) {
            if (error == null && Branch.getInstance().getCredits() > 5) {
                Branch.getInstance().redeemRewards(5);
            }
        }
    });
    

Comments