Referrals Web SDK Integration
This step by step guide outlines the functionality of GrowthScore Web SDK Integration for referrals and helps in smooth integration of the SDK into your web site or web App.
To use the Web SDK, you’ll need to first initialize the SDK with your GrowthScore App Key. You can find your App Key in your GrowthScore Dashboard.
Getting Started
Going forward, we shall be denoting the invitation or referral sender as ‘Referrer‘ and the receiver or beneficiary as ‘Friend‘. The integration is very straightforward.
GrowthScore Web SDK is an asynchronous library and uses a global queue to process the asynchronous API calls.
STEP 1: Installation
Configure Referral campaign on GrowthScore Dashboard and obtain the installation script block and gs_appkey from GS Dashboard > Referrals left side menu > Configure > Install tab.
Add the copied JavaScript at the end of your <body> tag on every page(pages where you want to use GrowthScore) in your website and initialize the SDK with logged-in user information.
Alternatively, you can copy the following Javascript and replace the ‘gs_appkey’ with your App key obtained from GS Dashboard > Referrals left side menu > Configure > Install tab.
<script>
(function(g,r,o,w,t,h,_,s,d,k){if(!g[w]||!g[w]._q){for(;s<_.length;)t(h,_[s++]);d=r.createElement(o);d.async=1;d.src="https://d3ixbrge5tdwth.cloudfront.net/gs/v1.1.2/build.min.js";k=r.getElementsByTagName(o)[0];k.parentNode.insertBefore(d,k);g[w]=h}})(window,document,"script","growthscore",function(g,r){g[r]=function(){g._q.push([r,arguments])}},{_q:[],_v:1},"init widget discardSurvey submitSurvey survey testimonials renderTestimonials referralWidget getTerms getFriendsList".split(" "), 0);
var gs_appkey = 'Your-Appkey';
growthscore.init(gs_appkey,
{
emailid: 'USER_EMAIL (required)',
/*firstname: 'FIRST_NAME',*/
/*lastname: 'LAST_NAME',*/
/*signupdate: 'SIGNUP_DATE (yyyy-mm-dd)',*/
/*storeid: 'USER_STOREID (External ID)',*/
/*referrer: 'REFERRERCODE (Referral Code provided on Signup)',*/
/*attributes: { custom_1: "C1_VALUE", custom_2:"C2_VALUE" }*/
}, function (err, data) {
/*Handle Error Data */
});
</script>
This will initialize the SDK asynchronous, please don’t forget to replace the ‘Your-Appkey’ with your app key.
Input Parameters
emailid (required) – User email address
firstname (optional) – First name of the user(used to greet the customer)
lastname (optional) – Last name of the user
signupdate (optional) – user’s original signup date in yyyy-mm-dd. if not provided GS will use the current date as signup date.
storeid (optional) – User id to identify user uniquely(External Id).
referrer (optional) – referrer code(friends referral code provided by the user during signup)
attributes (optional) – Any additional user attributes in JSON array.
Example: { account_type : “Premium” , Package : “growth” }
STEP 2: Launching Referral Widget
To launch the Referral widget as a popup, add class name ‘gs_refer_btn‘ to any button on your page.
<button class="gs_refer_btn">Launch Referrals</button>
STEP 3: On Friend Signup
Referrer clicks on ‘Refer & Earn’ button and invites his friend using the referral link. Friend clicks on the referral link and lands on signup page. On completion of friend signup, initialize the SDK with Friend details as explained in STEP 1.
STEP 4: Referral Attribution & Friend Reward
On completion of STEP 3, friend will be attributed to referrer automatically. if there is any reward configured for friend on GS Dashboard, friend reward will be generated and GS will fire “referral.reward.new” webhook.
If you want to reward the friend(newly signed-up user) using stripe discount, please connect the Stripe on GrowthScore Dashboard and use referrer’s referral code as a coupon code during stripe payment subscription. You can auto fill the referrer’s referral code using ‘getReferrerCode()’ callback.
Referral code can be used as coupon code in case if the reward is Stripe payment discount.
STEP 5: Generate Referrer Reward & Conversion Event
Referrer reward will be generated automatically if you are offering Stripe discount as a reward. GrowthScore will generate conversion events and process them automatically for Stripe based rewards. You need not make any explicit conversion events using API. Don’t forget to connect stripe on GrowthScore Dashboard, if want to offer Stripe discounts as referral reward.
In case of non Stripe based rewards, you need to send the conversion event using Register Conversion Event API to generate referrer reward. Referrer reward will be generated on successful conversion event and “referral.reward.new” webhook will be fired with reward information.
Rewards will be initially in the “Pending” state. After fraud check and on completion of review period(You can set review period on GrowthScore Dashboard to stop rewarding until completion of the mentioned days) rewards status will be changed to “Approved” or “Suspicious”.
“referral.reward.update” Webhook will be fired on each reward status change. Always check the reward status received in the webhook data and reward only if the status is “Approved”.
STEP 6: Credit the Rewards & Change the Reward Status
In case of non Stripe/non Coupon(coupons need to be uploaded in GrowthScore Dashboard and GS will distribute the rewards automatically) based rewards, you need to credit the rewards once you receive the webhook with reward status as “Approved”. After crediting the rewards, change the reward status to “Rewarded” using “Change Reward Status” API.
Once the reward status is changed to “Rewarded”, GS will send the reward notification to user if reward notifications are configured on GS Dashboard(Referrals (left menu) > Notifications > Referrer Credit Email).
Web SDK integration for GS Referrals is now complete. If you want to use any additional referral callbacks, please read the following section.
Additional Callbacks
Autofill the Referral Code
SDK callback ‘getReferrerCode()’ can be used to pickup the referral code from a cookie. The callback method will return the referral code which can be used to auto prefill the referral code during the Subscription/Signup. This call doesn’t require SDK initialization. This referral code will be used as a coupon code and could serve as a reward for the friend during the stripe subscription process.
growthscore.getReferrerCode(gs_appkey, function (err, data) {
response.html(err || JSON.stringify(data));
document.getElementById('refcode-input').value = data['referrercode'];
});
Get Referrer Details
SDK callback ‘getReferrer()’ can be used to get the referrer details. This callback is mainly useful to show a personalized landing page with referrer name. It helps to personalize the on boarding flow of a new user and improve the conversion rate. This call doesn’t require any SDK initialization.
gs_appkey is mandatory to enable this call. All other input parameters are optional. This callback automatically pics the referrer code from cookie and returns the referrer details.
If you make this call along with the referrer code as parameter, this will return the referrer details of the provided referral code. However, if you make this call with user email and no referrer code, callback will return the referrer details of the user email provided if available.
growthscore.getReferrer(gs_appkey,referrercode,useremail, function (err, data) {
});
Input Parameters
referrercode (optional) – invite code used by the user during signup/subscription
useremail (optional) – email of the current user for whom you want to get the referrer details
Output Parameters
referrercode – referrer code of the user
referrername – referrer name
friendreward – the current on boarding user reward
friendrewardunit – unit of the friend reward, like $ Credit or % Discount
friendrewardfrequency – reward duration, i.e. 3 months or 6 months
hasreferrer – ‘True’ if the user has referrer when you invoke the call with user email
isexistinguser – ‘True’ if the user already registered when you invoke the call with user email
success – ‘true’ if the API success
message – Any message from server if required
Register Conversion Event/Subscription
When a user subscribes to a plan or completes a transaction successfully, you have to register the conversion event to generate the rewards. If you are using Stripe as the payment method, GrowthScore handles the conversion events and you need not send the conversion events.
If you are using any other payment method, you have to register the conversion events from your backend server using GrowthScore API’s. Use API ‘registerconversionevent‘ as described here.
Get Rewards and Friends List
This callback is used to retrieve the friends list & user balance.
growthscore.getFriendsList(function (err, data) {
});
Output Parameters
rewardunit – unit of the reward, like $ Credit or % Discount
total – Total reward amount earned
claimed – Amount marked as rewarded
pending – amount yet to be rewarded
totalconvertedfriends – number of friends signedup
statuscode – 0 : Referrals disabled, 1 : Success
Get Code
This callback is used to retrieve the referrer’s referral code.
growthscore.getReferrerCode(gs_appkey, function (err, data) {
document.getElementById('refcode-input').value = data['referralcode'];
});
Output Parameters
referralcode – referrer’s referral code
Validate Code
This callback is used to validate a referral code for a user, to know if it is valid or not.
growthscore.validateCode(getInputVal('#validatecode-input'), function (err, data) {
});
Input Parameters
referralCode – Referrer’s referral code
Output Parameters
success – true, if the referral code is valid else False
message – Message from the server, if required
statuscode – 1 : Valid Referral Code, 2 : User is already attributed, 3 : Invalid Referral Code, 4: self referral and is invalid.
Apply Code
This callback is used to apply referral code for a user, to confirm the referrer.
growthscore.applyCode(getInputVal('#refcode-input'), function (err, data) {
});
Input Parameters
referralCode – Referrer’s referral code
Output Parameters
success – true, if the referral code applied successfully else False
message – Message from the server, if required
statuscode – 1 : successfully attributed, 2 : User is already attributed, 3 : Invalid Referral Code, 4: self referral and is invalid.
Get Terms
This callback is used to get the campaign’s terms and conditions as set on the dashboard.
growthscore.getTerms(function (err, data) {
});