Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cello.so/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to add referral tracking capabilities to your existing attribution links without creating new ones. In this guide, we’ll use Branch.io as an example. The implementation is similar if you use other attribution libraries like AppsFlyer, Singular or Adjust.
Mobile attribution builds on top of web attribution since users typically click referral links on web before downloading your app. The web setup captures the initial referral code that will later be attributed to the mobile app installation and signup.

​
Overview

The referral flow works as follows:
  • Existing user shares their unique referral link
  • New user clicks the link and is directed to your landing page
  • User then clicks on AppStore or Google Play app download
  • New user installs and opens the app
  • App receives referral data and attributes the installation
  • Backend records the referral during signup

​
Basic Concept

Instead of creating new links for each referrer, you’ll append referral data to your existing Branch.io (or other attribution library) app install link: 
Original: https://yourbrand.app.link/abc123
With Referral: https://yourbrand.app.link/abc123?referral_ucc=A1B2C

​
Data Persists Through Installation

When a user clicks the referral link, Branch.io stores the referral data (including the referral_ucc) in their servers and associates it with the user’s device fingerprint. This allows the data to persist through:
  • App Store redirect
  • App download
  • First app launch

​
Data Flow Sequence

https://yourbrand.app.link/abc123?referral_ucc=A1B2C
↓
Branch.io captures and stores:
- referral_ucc: A1B2C
- Device fingerprint
- Click timestamp

​
App Installation

User installs app from store
↓
Branch SDK initializes on first launch
↓
Branch matches device to stored click data
↓
Delivers referral data to app

​
Accessing Referral Data in Your App

​
iOS Implementation

import Branch

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, 
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
            // Check if the user came from a Branch link
            if let clickedBranchLink = params?["+clicked_branch_link"] as? Bool,
               clickedBranchLink {
                
                // Extract referral code
                if let referralCode = params?["referral_ucc"] as? String {
                    print("Referral Code: \(referralCode)")
                    
                    // Store for use during signup
                    UserDefaults.standard.set(referralCode, 
                                           forKey: "pending_referral_code")
                }
            }
        }
        return true
    }
}

​
Android Implementation

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        Branch.getAutoInstance(this).initSession({ branchUniversalObject, linkProperties, error ->
            if (error == null) {
                // Check if user came from Branch link
                if (linkProperties?.has("+clicked_branch_link") == true) {
                    // Get referral code
                    val referralCode = linkProperties.get("referral_ucc")
                    referralCode?.let {
                        Log.d("Branch", "Referral Code: $it")
                        
                        // Store for signup
                        getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
                            .edit()
                            .putString("pending_referral_code", it)
                            .apply()
                    }
                }
            }
        }, this.intent.data, this)
    }
}

​
React Native Implementation

import branch from 'react-native-branch';

function DeepLinkHandler() {
  useEffect(() => {
    // Handle deep link when app is already running
    const subscription = branch.subscribe({
      onNewIntent: ({ error, params, uri }) => {
        if (error) {
          console.error('Branch link error:', error);
          return;
        }

        if (params['+clicked_branch_link']) {
          handleDeepLink(params);
        }
      }
    });

    return () => subscription();
  }, []);

  const handleDeepLink = async (params) => {
    const referralCode = params.referral_ucc;
    if (referralCode) {
      await AsyncStorage.setItem('pending_referral_code', referralCode);
      // Handle navigation or other logic based on deep link
    }
  };

  return null;
}

​
Using the Referral Data During Signup

When the user completes signup, retrieve the stored referral code and include it in your signup API call:

​
iOS Implementation

// iOS Example
class SignupViewController: UIViewController {
    func completeSignup(email: String, password: String) {
        // Get stored referral code
        let referralCode = UserDefaults.standard.string(forKey: "pending_referral_code")
        
        // Include in signup API call
        let signupData = [
            "email": email,
            "password": password,
            "referral_code": referralCode
        ]
        
        api.signup(signupData) { result in
            if result.success {
                // Clear stored referral data after successful signup
                UserDefaults.standard.removeObject(forKey: "pending_referral_code")
            }
        }
    }
}

​
Android Implementation

// Android Example
class SignupActivity : AppCompatActivity() {
    private fun completeSignup(email: String, password: String) {
        val prefs = getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
        val referralCode = prefs.getString("pending_referral_code", null)
        
        val signupData = HashMap<String, String>().apply {
            put("email", email)
            put("password", password)
            referralCode?.let { put("referral_code", it) }
        }
        
        api.signup(signupData) { success ->
            if (success) {
                // Clear stored referral data
                prefs.edit().remove("pending_referral_code").apply()
            }
        }
    }
}

​
React Native Implementation

function SignupScreen({ navigation }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleSignup = async () => {
    try {
      const referralCode = await AsyncStorage.getItem('pending_referral_code');
      
      const response = await api.signup({
        email,
        password,
        referral_code: referralCode
      });

      if (response.success) {
        await AsyncStorage.removeItem('pending_referral_code');
        navigation.navigate('Home');
      }
    } catch (error) {
      console.error('Signup error:', error);
    }
  };

  return (
    // Your signup form JSX
  );
}