One of the most effective ways to get new users is through user referrals. You can use Dynamic Links along with Realtime Database and Cloud Functions for Firebase to encourage your users to invite their friends by offering in-app rewards for successful referrals to both the referrer and the recipient.
Key benefits
- Accelerate growth by providing an incentive for your users to invite their friends.
- Invitation links work across platforms.
- New users opening your app for the first time get a first-run experience that you customize for them. For example, you can automatically connect them with the friend that invited them.
- Optionally delay granting rewards until new users complete some introductory task, such as completing a tutorial.
Here's how to get started!
Set up Firebase and the Dynamic Links SDK
Set up a new Firebase project and install the Dynamic Links SDK into your app. (iOS, Android, C++, Unity). Installing the Dynamic Links SDK allows Firebase to pass along data about the Dynamic Link to the app, including after the user installs the app. Without the SDK, there's no way to connect a post-install user with a pre-install click.
Create invitation links
To create an invitation, first create the link that the recipient opens to accept the invitation. Later, you will include this link in the text of the invitation. When a recipient of the invitation installs your app by opening the link, they can get a customized first-run experience, including receiving an in-app reward.
This invitation link is a Dynamic Link with a link parameter value that indicates
it is from your existing user.
There are many ways you can format these link parameter payloads and tie them
into your app. One simple way is to specify the sender's user account ID in a
query parameter like in the following example:
https://mygame.example.com/?invitedby=SENDER_UID
Then, to create Dynamic Links suitable for inclusion in an invitation, you can use the Dynamic Link Builder API:
iOS (Swift)
guard let uid = Auth.auth().currentUser?.uid else { return }
let link = URL(string: "https://mygame.example.com/?invitedby=\(uid)")
let referralLink = DynamicLinkComponents(link: link!, domain: "example.page.link")
referralLink.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
referralLink.iOSParameters?.minimumAppVersion = "1.0.1"
referralLink.iOSParameters?.appStoreID = "123456789"
referralLink.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")
referralLink.androidParameters?.minimumVersion = 125
referralLink.shorten { (shortURL, warnings, error) in
if let error = error {
print(error.localizedDescription)
return
}
self.invitationUrl = shortURL
}
Java
FirebaseUser user = FirebaseAuth.getInstance().getCurrentUser();
String uid = user.getUid();
String link = "https://mygame.example.com/?invitedby=" + uid;
FirebaseDynamicLinks.getInstance().createDynamicLink()
.setLink(Uri.parse(link))
.setDomainUriPrefix("https://example.page.link")
.setAndroidParameters(
new DynamicLink.AndroidParameters.Builder("com.example.android")
.setMinimumVersion(125)
.build())
.setIosParameters(
new DynamicLink.IosParameters.Builder("com.example.ios")
.setAppStoreId("123456789")
.setMinimumVersion("1.0.1")
.build())
.buildShortDynamicLink()
.addOnSuccessListener(new OnSuccessListener<ShortDynamicLink>() {
@Override
public void onSuccess(ShortDynamicLink shortDynamicLink) {
mInvitationUrl = shortDynamicLink.getShortLink();
// ...
}
});Kotlin
val user = FirebaseAuth.getInstance().currentUser
val uid = user!!.uid
val link = "https://mygame.example.com/?invitedby=$uid"
FirebaseDynamicLinks.getInstance().createDynamicLink()
.setLink(Uri.parse(link))
.setDomainUriPrefix("https://example.page.link")
.setAndroidParameters(
DynamicLink.AndroidParameters.Builder("com.example.android")
.setMinimumVersion(125)
.build())
.setIosParameters(
DynamicLink.IosParameters.Builder("com.example.ios")
.setAppStoreId("123456789")
.setMinimumVersion("1.0.1")
.build())
.buildShortDynamicLink()
.addOnSuccessListener { shortDynamicLink ->
mInvitationUrl = shortDynamicLink.shortLink
// ...
}Send the invitations
Now that you have created the link, you can include it in an invitation. The invitation can be an email, SMS message, or any other medium, depending on what is most appropriate for your app and audience.
For example, to send an email invitation:
iOS (Swift)
guard let referrerName = Auth.auth().currentUser?.displayName else { return }
let subject = "\(referrerName) wants you to play MyExampleGame!"
let invitationLink = invitationUrl?.absoluteString
let msg = "<p>Let's play MyExampleGame together! Use my <a href=\"\(invitationLink)\">referrer link</a>!</p>"
if !MFMailComposeViewController.canSendMail() {
// Device can't send email
return
}
let mailer = MFMailComposeViewController()
mailer.mailComposeDelegate = self
mailer.setSubject(subject)
mailer.setMessageBody(msg, isHTML: true)
myView.present(mailer, animated: true, completion: nil)
Java
String referrerName = FirebaseAuth.getInstance().getCurrentUser().getDisplayName();
String subject = String.format("%s wants you to play MyExampleGame!", referrerName);
String invitationLink = mInvitationUrl.toString();
String msg = "Let's play MyExampleGame together! Use my referrer link: "
+ invitationLink;
String msgHtml = String.format("<p>Let's play MyExampleGame together! Use my "
+ "<a href=\"%s\">referrer link</a>!</p>", invitationLink);
Intent intent = new Intent(Intent.ACTION_SENDTO);
intent.setData(Uri.parse("mailto:")); // only email apps should handle this
intent.putExtra(Intent.EXTRA_SUBJECT, subject);
intent.putExtra(Intent.EXTRA_TEXT, msg);
intent.putExtra(Intent.EXTRA_HTML_TEXT, msgHtml);
if (intent.resolveActivity(getPackageManager()) != null) {
startActivity(intent);
}Kotlin
val referrerName = FirebaseAuth.getInstance().currentUser?.displayName
val subject = String.format("%s wants you to play MyExampleGame!", referrerName)
val invitationLink = mInvitationUrl.toString()
val msg = "Let's play MyExampleGame together! Use my referrer link: $invitationLink"
val msgHtml = String.format("<p>Let's play MyExampleGame together! Use my " +
"<a href=\"%s\">referrer link</a>!</p>", invitationLink)
val intent = Intent(Intent.ACTION_SENDTO)
intent.data = Uri.parse("mailto:") // only email apps should handle this
intent.putExtra(Intent.EXTRA_SUBJECT, subject)
intent.putExtra(Intent.EXTRA_TEXT, msg)
intent.putExtra(Intent.EXTRA_HTML_TEXT, msgHtml)
if (intent.resolveActivity(packageManager) != null) {
startActivity(intent)
}Retrieve referral information in your app
When the invitation recipient opens the referral link, they will be directed to the App Store or Play Store to install your app if it isn't already installed. Then, when they open your app for the first time, you can retrieve the referral information you included in the Dynamic Link and use it to apply the reward.
Usually, you want to grant referral rewards only after the invitation recipient signs up, or even only after the new user completes some task. Until the reward criteria are met, you need to keep track of the reward information that you got from the Dynamic Link.
One way to keep track of this information is sign in the user anonymously and store the data in the anonymous account's Realtime Database record. When the recipient signs up and the anonymous account is converted to a permanent account, the new account will have the same UID as the anonymous account, and as a result, will have access to the reward information.
For example, to save the referrer's UID after the recipient opens your app:
iOS (Swift)
func application(_ app: UIApplication, open url: URL, options:
[UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
if let isDynamicLink = DynamicLinks.dynamicLinks()?.shouldHandleDynamicLink(fromCustomSchemeURL: url),
isDynamicLink {
let dynamicLink = DynamicLinks.dynamicLinks()?.dynamicLink(fromCustomSchemeURL: url)
return handleDynamicLink(dynamicLink)
}
// Handle incoming URL with other methods as necessary
// ...
return false
}
@available(iOS 8.0, *)
func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
guard let dynamicLinks = DynamicLinks.dynamicLinks() else { return false }
let handled = dynamicLinks.handleUniversalLink(userActivity.webpageURL!) { (dynamicLink, error) in
if (dynamicLink != nil) && !(error != nil) {
self.handleDynamicLink(dynamicLink)
}
}
if !handled {
// Handle incoming URL with other methods as necessary
// ...
}
return handled
}
func handleDynamicLink(_ dynamicLink: DynamicLink?) -> Bool {
guard let dynamicLink = dynamicLink else { return false }
guard let deepLink = dynamicLink.url else { return false }
let queryItems = URLComponents(url: deepLink, resolvingAgainstBaseURL: true)?.queryItems
let invitedBy = queryItems?.filter({(item) in item.name == "invitedby"}).first?.value
let user = Auth.auth().currentUser
// If the user isn't signed in and the app was opened via an invitation
// link, sign in the user anonymously and record the referrer UID in the
// user's RTDB record.
if user == nil && invitedBy != nil {
Auth.auth().signInAnonymously() { (user, error) in
if let user = user {
let userRecord = Database.database().reference().child("users").child(user.uid)
userRecord.child("referred_by").setValue(invitedBy)
if dynamicLink.matchConfidence == .weak {
// If the Dynamic Link has a weak match confidence, it is possible
// that the current device isn't the same device on which the invitation
// link was originally opened. The way you handle this situation
// depends on your app, but in general, you should avoid exposing
// personal information, such as the referrer's email address, to
// the user.
}
}
}
}
return true
}
Java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// ...
FirebaseDynamicLinks.getInstance()
.getDynamicLink(getIntent())
.addOnSuccessListener(this, new OnSuccessListener<PendingDynamicLinkData>() {
@Override
public void onSuccess(PendingDynamicLinkData pendingDynamicLinkData) {
// Get deep link from result (may be null if no link is found)
Uri deepLink = null;
if (pendingDynamicLinkData != null) {
deepLink = pendingDynamicLinkData.getLink();
}
//
// If the user isn't signed in and the pending Dynamic Link is
// an invitation, sign in the user anonymously, and record the
// referrer's UID.
//
FirebaseUser user = FirebaseAuth.getInstance().getCurrentUser();
if (user == null
&& deepLink != null
&& deepLink.getBooleanQueryParameter("invitedby", false)) {
String referrerUid = deepLink.getQueryParameter("invitedby");
createAnonymousAccountWithReferrerInfo(referrerUid);
}
}
});
}
private void createAnonymousAccountWithReferrerInfo(final String referrerUid) {
FirebaseAuth.getInstance()
.signInAnonymously()
.addOnSuccessListener(new OnSuccessListener<AuthResult>() {
@Override
public void onSuccess(AuthResult authResult) {
// Keep track of the referrer in the RTDB. Database calls
// will depend on the structure of your app's RTDB.
FirebaseUser user = FirebaseAuth.getInstance().getCurrentUser();
DatabaseReference userRecord =
FirebaseDatabase.getInstance().getReference()
.child("users")
.child(user.getUid());
userRecord.child("referred_by").setValue(referrerUid);
}
});
}Kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// ...
FirebaseDynamicLinks.getInstance()
.getDynamicLink(intent)
.addOnSuccessListener(this) { pendingDynamicLinkData ->
// Get deep link from result (may be null if no link is found)
var deepLink: Uri? = null
if (pendingDynamicLinkData != null) {
deepLink = pendingDynamicLinkData.link
}
//
// If the user isn't signed in and the pending Dynamic Link is
// an invitation, sign in the user anonymously, and record the
// referrer's UID.
//
val user = FirebaseAuth.getInstance().currentUser
if (user == null &&
deepLink != null &&
deepLink.getBooleanQueryParameter("invitedby", false)) {
val referrerUid = deepLink.getQueryParameter("invitedby")
createAnonymousAccountWithReferrerInfo(referrerUid)
}
}
}
private fun createAnonymousAccountWithReferrerInfo(referrerUid: String?) {
FirebaseAuth.getInstance()
.signInAnonymously()
.addOnSuccessListener {
// Keep track of the referrer in the RTDB. Database calls
// will depend on the structure of your app's RTDB.
val user = FirebaseAuth.getInstance().currentUser
val userRecord = FirebaseDatabase.getInstance().reference
.child("users")
.child(user!!.uid)
userRecord.child("referred_by").setValue(referrerUid)
}
}Then, when the invitation recipient decides to create an account, you can carry over the referral information from the anonymous account to the invitation recipient's new account.
First, get an AuthCredential object using the sign-in method the invitee wants
to use. For example, to sign-in with an email address and password:
iOS (Swift)
let credential = EmailAuthProvider.credential(withEmail: email, password: password)
Java
AuthCredential credential = EmailAuthProvider.getCredential(email, password);
Kotlin
val credential = EmailAuthProvider.getCredential(email, password)
Then, link this credential to the anonymous account:
iOS (Swift)
if let user = Auth.auth().currentUser {
user.link(with: credential) { (user, error) in
// Complete any post sign-up tasks here.
}
}
Java
FirebaseAuth.getInstance().getCurrentUser()
.linkWithCredential(credential)
.addOnSuccessListener(new OnSuccessListener<AuthResult>() {
@Override
public void onSuccess(AuthResult authResult) {
// Complete any post sign-up tasks here.
}
});Kotlin
FirebaseAuth.getInstance().currentUser!!
.linkWithCredential(credential)
.addOnSuccessListener {
// Complete any post sign-up tasks here.
}The new, permanent, account has access to all of the reward data you added to the anonymous account.
Grant rewards to the referrer and the recipient
Now that you have retrieved and saved the invitation data from the Dynamic Link, you can grant the referral rewards to the referrer and the recipient whenever the criteria you want to require have been met.
Although you can write to the Realtime Database from your client app, you will often want to allow only read access to data like in-app currency from your apps, and perform write operations only from your backend. This backend could be any system capable of running the Firebase Admin SDK, but it is often easiest to use Cloud Functions to perform these tasks.
For example, suppose you have a game and you want to grant a reward of in-game currency to the recipient after the recipient signs up, and to the referrer after the recipient reaches level 5.
To grant the reward for signing up, deploy a function that watches for a specific Realtime Database key to be created, and grants the reward when it is. For example:
const functions = require('firebase-functions');
const admin = require('firebase-admin');
admin.initializeApp(functions.config().firebase);
exports.grantSignupReward = functions.database.ref('/users/{uid}/last_signin_at')
.onCreate(event => {
var uid = event.params.uid;
admin.database().ref(`users/${uid}/referred_by`)
.once('value').then(function(data) {
var referred_by_somebody = data.val();
if (referred_by_somebody) {
var moneyRef = admin.database()
.ref(`/users/${uid}/inventory/pieces_of_eight`);
moneyRef.transaction(function (current_value) {
return (current_value || 0) + 50;
});
}
});
});
Then, when a new user signs up, trigger this function by creating the
Realtime Database key. For example, trigger the function in linkWithCredential's
success listener, which you created in the previous step:
iOS (Swift)
if let user = Auth.auth().currentUser {
user.link(with: credential) { (user, error) in
// Complete any post sign-up tasks here.
// Trigger the sign-up reward function by creating the "last_signin_at" field.
// (If this is a value you want to track, you would also update this field in
// the success listeners of your Firebase Authentication signIn calls.)
if let user = user {
let userRecord = Database.database().reference().child("users").child(user.uid)
userRecord.child("last_signin_at").setValue(ServerValue.timestamp())
}
}
}
Java
FirebaseAuth.getInstance().getCurrentUser()
.linkWithCredential(credential)
.addOnSuccessListener(new OnSuccessListener<AuthResult>() {
@Override
public void onSuccess(AuthResult authResult) {
// Complete any post sign-up tasks here.
// Trigger the sign-up reward function by creating the
// "last_signin_at" field. (If this is a value you want to track,
// you would also update this field in the success listeners of
// your Firebase Authentication signIn calls.)
FirebaseUser user = FirebaseAuth.getInstance().getCurrentUser();
DatabaseReference userRecord =
FirebaseDatabase.getInstance().getReference()
.child("users")
.child(user.getUid());
userRecord.child("last_signin_at").setValue(ServerValue.TIMESTAMP);
}
});Kotlin
FirebaseAuth.getInstance().currentUser!!
.linkWithCredential(credential)
.addOnSuccessListener {
// Complete any post sign-up tasks here.
// Trigger the sign-up reward function by creating the
// "last_signin_at" field. (If this is a value you want to track,
// you would also update this field in the success listeners of
// your Firebase Authentication signIn calls.)
val user = FirebaseAuth.getInstance().currentUser
val userRecord = FirebaseDatabase.getInstance().reference
.child("users")
.child(user!!.uid)
userRecord.child("last_signin_at").setValue(ServerValue.TIMESTAMP)
}To grant a reward to the referrer when the recipient reaches level 5, deploy a
function that watches for changes to the level field in your user records. If
a user went from level 4 to level 5, and the user has a referrer recorded, grant
the reward:
const functions = require('firebase-functions');
const admin = require('firebase-admin');
admin.initializeApp(functions.config().firebase);
exports.rewardReferrals = functions.database.ref('/users/{uid}/level')
.onUpdate(event => {
var level = event.data.val();
var prev_level = event.data.previous.val();
if (prev_level == 4 && level == 5) {
var referrerRef = event.data.ref.parent.child('referred_by');
return referrerRef.once('value').then(function(data) {
var referrerUid = data.val();
if (referrerUid) {
var moneyRef = admin.database()
.ref(`/users/${referrerUid}/inventory/pieces_of_eight`);
return moneyRef.transaction(function (current_value) {
return (current_value || 0) + 50;
});
}
});
}
});
Both the referrer and your new user have now received their rewards.