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_REFERRERiOS 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
- add referrer dependency
- after fist onboarding getInstallReferrer and call https api?
- done ?
PR: status-im/status-mobile#10139
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent