Integration Steps

The SaaS Referral Program Guide outlines the functionality of AppVirality SaaS Web SDK , and helps in easy integration of the SDK into your web site or web App.

To use the Web SDK, you will need to first initialize the SDK with your AppVirality App Key. You can find your App Key in your AppVirality Dashboard. You will register the users by calling init() upon a user login and call logout when user clicks on logout.

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. AppVirality Web SDK is an asynchronous library and uses global queue to process the asynchronous API calls.

STEP 1: Installation

Add the following JavaScript at the end of your <body> tag on every page in your application and initialize the SDK with logged-in user information.

(function(a,p,v,i,r,l,_,s,d,k){if(!a[i]||!a[i]._q){for(;s<_.length;)r(l,_[s++]);d=p.createElement(v);d.async=1;d.src="https://s3-us-west-2.amazonaws.com/avgrowthcontent/saas/build.min.js";k=p.getElementsByTagName(v)[0];k.parentNode.insertBefore(d,k);a[i]=l}})(window,document,"script","appvirality",function(a,p){a[p]=function(){a._q.push([p,arguments])}},{_q:[],_v:1},"init logout getTerms RI getCampaignData recordSocialAction getUserBalance getFriendsList applyCode validateCode widget getReferrerCode getReferrer".split(" "),0);

var appkey  = 'APPVIRALITY-KEY';
      //initialize the SDK
        appvirality.init(appkey,
            {
                email: '',
                name: '',
                code: '',
                country: '',
                useraccountid: '',
                profileimage: '',
                phone: '',
                stripecustomerid: ''
            }, function (err, data) {

});

While initializing the SDK in an asynchoronous process with a callback method, please ensure to replace “APPVIRALITY-KEY” with your App key. Once you’ve registered with appvirality.com and added a new app, you should have an App Key

Init - Input Parameters

Params	Description
appkey	App key provided by AppVirality > Dashboard > AppDetails
email	User’s email address
name (optional)	First Name of the user required to personalize the referral messages
code (optional)	Referrer’s Referral Code If friend enters during registration
useraccountid (optional)	ID of the user in your App helps to identify users on dashboard as you do in your app(must be unique for every user)
profileimage (optional)	User profile picture URL required to personalize the referral messages
phone (optional)	User’s mobile number
city	User’s city
state (optional)	User’s state
country (optional)	User’s country
stripecustomerid (optional)	User StripeID

Init - Output Parameters

Data Params	Description
userkey	Unique id generated by AppVirality for each registered user
hasreferrer	it will be ‘true’ if the user has referrer
isexistinguser	it will be ‘true’ if the user already registered
shareurl	user share Link used to invite friends
saascampaignid	referral campaign id
referralcode	user referral code used to invite friends
success	‘True’ if the API success
message	Any message from server if required

To launch the Referral widget as popup, add class name ‘av_refer_btn’ to any button on your page.

    <button class="av_refer_btn">Launch Referrals</button>

STEP 3: 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 refill 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.

            appvirality.getReferrerCode(appkey, function (err, data) {
                document.getElementById('refcode-input').value = data['referrercode']
            });

STEP 4: 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 and profile picture. 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.

Appkey is mandatory 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 (or useraccountid) and no referrer code, callback will return the referrer details of the user email provided if available.

            appvirality.getReferrer(appkey,referrercode,useremail,useraccountid, function (err, data) {

});

getReferrer - Input Parameters

Params	Description
appkey	App key provided by AppVirality > Dashboard > AppDetails
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
useraccountid (optional)	ID of the user in your App helps to identify users on dashboard as you do in your app(must be unique for every user)

getReferrer - Output Parameters

Data Params	Description
referrercode	referrer code of the user
referrername	referrer name
profileimage	profile image url of the referrer
friendreward	the current on boarding user reward
friendrewardunit	unit of the friend reward, like $ or %
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
userkey	Unique id generated by AppVirality for each registered user
success	‘True’ if the API success
message	Any message from server if required

STEP 5: 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, AppVirality 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 AppVirality API’s. Use API ‘registerconversionevent’ as described here : /docs/saas-referrals/apis/register-conversion-event/

This concludes the SDK integration for SaaS Referrals.