User referral program

[rachelhamlin]

Referral Implementation Steps

Source

Android Only

Goal

We need to acquire users.

We will do so allowing people to append an invite code to a join.status.im url, in which they'll earn SNT for successful onboarding and/or purchase or starterpack

Practically speaking this will look like:

• Friend Referrals (Earn SNT for referring friend)
• Advertising Campaigns promoting DApps

This is the first non-idealistic iteration of our user aquisition engine as promised in the whitepaper.

App Modifications

Android Only

• App Install Attribution for both Google Play and Apple App Store
  • Android com.android.vending.INSTALL_REFERRER
  • iOS Advertising Identifier (IDFA/SKAdNetwork)
• out exists in referral data, treat as universal link and open chat/public chat/dapp browser after onboarding
• If a invite code exists in referral data, make an HTTPS post Request after Onboarding
• Android Change Image to show "Earn SNT, Invite a Friend" (Ask Carl for copy)
• include invite code with starterpack receipt validation

Attribution & Payout Service

Jarrad will do this, only focus on the app modifications.

Flows

Friend shares a join link with an invite code (join.status.im/0x0...?invite=f79989f679386be7aa56dc1c4) to new user
new user opens link (we track them)
link redirects new user to google play / app store / get page
depending on the out variable in referrer the app should after onboarding:

• open chat with user
• open chat with public chat
• open webpage in dapp browser

similar to how a universal link works if the app is installed

there are 2 postbacks to join.status.im with the invite code

• after onboarding join.status.im/event
• when validating starterpack purchase join.status.im/event

Implementation

Android

This is only for builds deployed to Google Play only, this won't work for direct apk installs and the code shouldn't be present.
(not independent apk)

• User presses Invite friend or share their chat key (public key)
• App makes a http post request to https://join.status.im/register
  • returns success or failure reason
    the invite code is a truncated hash of the signature, which is constructed by producing a json as a msg, signing the msg, and producing a json that contains the signature information:

The actual payloads for registration and events look like this
https://github.com/status-im/starterpack-service/blob/master/scripts/geth.js

and will record a the invite code, a truncated (first 25 chars) sha3 of the signature.
the app can generate invite codes itself for instant referral links

web3.sha3(sig).substring(2,27)
'f79989f679386be7aa56dc1c4'

• the app generates link and the user shares it with their friend

https://join.status.im/0x04abcXYZ123...?invite=f79989f679386be7aa56dc1c4
https://join.status.im/@jakubgs?invite=f79989f679386be7aa56dc1c4
https://join.status.im/@jakubgs.eth?invite=f79989f679386be7aa56dc1c4
https://join.status.im/markets?invite=f79989f679386be7aa56dc1c4
https://join.status.im/b/ens.domains?invite=f79989f679386be7aa56dc1c4

which will redirect to

https://play.google.com/store/apps/details?id=im.status.ethereum&referrer=out%3D0x04abcXYZ123...%26invite%3Df79989f679386be7aa56dc1c4
https://play.google.com/store/apps/details?id=im.status.ethereum&referrer=out%3D@jakubgs%26invite%3Df79989f679386be7aa56dc1c4
https://play.google.com/store/apps/details?id=im.status.ethereum&referrer=out%3Db%2Fens.domains%26invite%3Df79989f679386be7aa56dc1c4

additionally advertisers require 1 more parameter cid so join.status.im will also have to forward this param to gplay
ie
https://join.status.im/0x000...?invite=f79989f679386be7aa56dc1c4&cid=foo
https://play.google.com/store/apps/details?id=im.status.ethereum&referrer=out%3D0x000...%26invite%3Df79989f679386be7aa56dc1c4%26cid%3Dfoo

out is the post-onboarding action to perform (same as universal link)
invite is the invite code (needs to be sent in /event postback and /validate)
cid is clickid for advertising networks (needs to be sent in /event postback /validate)

WARN: this is pseudo-code
better to use the install referrer api below

We need to create a BroadcastReceiver that can record the values

and register it in the AndroidManifest.xml

<receiver
android:exported="true"
android:name="im.status.ethereum.receivers.InstallReceiver">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>

@Override
public void onReceive(Context context, Intent intent) {
        String rawReferrerString = intent.getStringExtra("referrer");
        if(rawReferrerString != null) {
// do stuff
Map<String, String> referralParams = new HashMap<String, String>();
try {
referrer = URLDecoder.decode(referrer, "x-www-form-urlencoded");
} catch (UnsupportedEncodingException e) { return; }

// Parse the query string, extracting the relevant data
String[] params = referrer.split("&");
for (String param : params) {
String[] pair = param.split("=");
referralParams.put(pair[0], pair[1]);
}
}
}

Once we receive the parameters

Apple

Android Only

Spoke with Carl, you're right, let's forget Apple.

Without our own Advertiser Keys or Skadnetwork - iOS doesn't seem feasible.

I have no idea how IDFA works but it can be used for app install attribution
Looks like apple rolled out skadnetwork in StoreKit
https://developer.apple.com/documentation/storekit/skadnetwork
https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback

Android Google Play Install Referrer

Play Store will no longer broadcast the "install_referrer" in March 2020, this is a new way how it should be used

https://developer.android.com/google/play/installreferrer

Google Play Install Referrer

You can use the Google Play Store's Install Referrer API to securely retrieve referral content from Google Play, such as:

The referrer URL of the installed package.
The timestamp, in seconds, of when a referrer click happened.
The timestamp, in seconds, of when an installation began.
Whether the user has interacted with your app's instant experience in the past 7 days.

Requirements

The Install Referrer API is exposed by the Google Play Store app on a device. Devices with a Google Play app version of 8.3.73 or later automatically have access to the API.

You must also have a Google Play Console account to use the Install Referrer API.

ReferrerDetails response = referrerClient.getInstallReferrer();
String referrerUrl = response.getInstallReferrer();
long referrerClickTime = response.getReferrerClickTimestampSeconds();
long appInstallTime = response.getInstallBeginTimestampSeconds();
boolean instantExperienceLaunched = response.getGooglePlayInstantParam();

Caution: The install referrer information will be available for 90 days and won't change unless the application is reinstalled. To avoid unnecessary API calls in your app, you should invoke the API only once during the first execution after install.

RN lib: https://github.com/Gretchin/react-native-install-referrer

The big question is , how to test this API ?
Old way, can't be used now https://tune.docs.branch.io/sdk/testing-the-google-play-install-referrer/

Second question how we'll track reinstalls ? say user onboarded reinstalled app and onboard again
[JH] this is done server-side, not an app concern

status-react implementation steps

1. add referrer dependency
2. after fist onboarding getInstallReferrer and call https api?
3. done ?

PR: status-im/status-mobile#10139

• read referrer
• call https with referrer