Callbacks

The AppVirality Web SDK for SaaS is now leaner & more effective. Like any SDK based solution, this one employs a lot of callbacks internally which help it to gather data points or info.

We shall explore & lay out the key elements that compose these callback.
We shall also discover what each of these callbacks intend to achieve.

The idea here is to simply help you as a developer understand the system, and enable you to adapt your integration to suit specific needs of your app. Below is the list of Callbacks defined inside the SDK for its interoperability:

AppVirality Initialization (Init)

Initialize the SDK

This callback is used while initializing the AppVirality Web SDK. This will be the first callback used before using any other callback except ‘getReferrerCode’ and ‘getReferrer’ callbacks.
Initializing the SDK is critical to loading of the referral campaign details & retrieving user relevant info to use forward in the subsequent activities.

The callback returns a bunch of details about the user, like:

User Key (most important among all other details)
Whether user has a Referrer
Is an Existing User or not
Referral campaign details to be presented on Widget etc.

Below code block is how it is implemented:

appvirality.init(appkey,
    {
    email: USER-EMAIL,
    name: USER-NAME,
    code: REFERRER-CODE,
    country: USER-COUNTRY,
    useraccountid: USER-ACCOUNTID,
    profileimage: USER-PROFILEPICURL,
    phone: USER-MOBILENUMBER,
    stripecustomerid: USER-STRIPECUSTOMERID
    }, function (err, data) {

});

Init - Input Parameters

Parameter	Type	Description
appkey	String	App key provided by AppVirality > Dashboard > AppDetails
email	String	User’s email address
name (optional)	String	First Name of the user required to personalize the referral messages
code (optional)	String	Referrer’s Referral Code If friend enters during registration
useraccountid (optional)	String	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)	String	User profile picture URL required to personalize the referral messages
phone (optional)	String	User’s mobile number
city	String	User’s city
state (optional)	String	User’s state
country (optional)	String	User’s country
stripecustomerid (optional)	String	User StripeID

Init - Output Parameters

Parameter	Type	Description
userkey	String	Unique id generated by AppVirality for each registered user
hasreferrer	boolean	It will be ‘true’ if the user has referrer
isexistinguser	boolean	It will be ‘true’ if the user already registered
shareurl	String	User share Link used to invite friends
saascampaignid	String	Referral campaign id
referralcode	String	User referral code used to invite friends
success	boolean	‘True’ if the API call is successful
message	String	Any message from server if required

Get Campaign Details

This callback is useful to retrieve the campaign details to display the referral widget. This callback requires SDK initialization.

appvirality.getCampaignData(function (err, data) {

});

Campaign Details contains the following information:

Campaign Data - Output Parameters

Parameters Explained

Parameter	Type	Decription
appid	String	Identifier for the app added in AppVirality Dashboard
campaignid	String	Identifier for the campaign
campaignname	String	Name of the campaign as set on the dashboard
offertitle	String	URL-encoded Campaign Title as set on dashboard
offerdescription	String	URL-encoded Campaign Description as set on dashboard
campaignbgcolor	String	Background color code for the campaign
campaignstartdate	String	campaign start date
widgetfont	String	Font name to be used in Widget
lastmodifieddate	String	Last date on which campaign has been modified
socialactions	Array<socialactions>	List of social actions configured on dashboard for sharing
customdomain	String	Custom Domain configured to be used in share link
rewardtype	String	it will be from 0 to 3. Where 0 - no rewards, 1- reward for only referrer,2- reward for only friend,3-both referrer and friend have rewards.
rewardrules	Array<rewardrules>	List of reward rules configured on dashboard
success	boolean	True- on API success
message	String	Message from server if required.

socialactions Explained

Parameter	Type	Decription
socialactionid	String	Identifier for the social channel
socialactionname	String	Name of the social action
sharemessage	String	URL-encoded share message as set on dashboard
sharetitle	String	URL-encoded share title as set on dashboard
shareimageurl	String	image url to be shared on social channel
displayorder	String	display order for social action while displaying on widget
emailaccountconfigured	boolean	it will be true if the email account configured on Dashboard to process invites.

rewardrules Explained

Parameter	Type	Decription
campaignid	int	Identifier for the campaign
rewardusertype	String	Reward user, either Referrer or Friend
eventname	String	Name of the event on which reward will be processed.
reward	int	Reward Value
rewardunit	String	Reward Unit, like ’$ credit’ or ’% discount’
rewardfrequency	int	Number of times the reward can be given.
mintranvalue	int	Minimum Transaction Value required to process reward in case of transaction based reward rule.
maxrewardamount	int	Maximum reward amount that can be awarded for this event.

This callback will record the user social actions and process the invitation emails if SMTP email account is configured in AppVirality Dashboard.

appvirality.recordSocialAction(mailBody.value, socialActionId, mailTo.value, mailSubject.value, function (err, data) {
  if (!err) {
    if (data['mailsent']) {
      //successfully sent email
    }
    else {
      //failed to send email
    }
  }
});

RecordSocialAction - Input Parameters

Parameter	Type	Description
MailBody/SharingMessage	String	Email body, if email is invite channel or Message shared by the user for all other invite channels
socialactionid	String	identifier for the social action, which will be available from campaign details
mailto (optional)	String	comma separated To-eamil id’s if the invite channel is email
mailsubject (optional)	String	mail subject if the invite channel is email

RecordSocialAction - Output Parameters

Parameter	Type	Description
mailsent	boolean	True - if the email sent successfully

Get Terms

This callback is used to get the campaign’s terms and conditions as set on the dashboard.

appvirality.getTerms(function (err, data) {

});

Get Terms - Output Parameters

Parameters Explained

Parameter	Type	Decription
success	boolean	True, if API call was successful else False
message	String	Campaign’s Terms and Conditions

Get User Balance

This callback is used to retrieve the user balance.

appvirality.getUserBalance(function (err, data) {

});

Get User Balance - Output Parameters

Parameters Explained

Parameter	Type	Decription
userbalance	Array<userbalance>	Array of user balance details
success	boolean	True, if API call was successful else False
message	String	Message from the server, if required

userbalance Explained

Parameter	Type	Decription
rewardunit	String	Reward amount unit
total	int	Total reward amount earned
claimed	int	Reward amount claimed
pending	int	Reward amount pending

Get Friends List

This callback is used to retrieve the list of friends for the logged-in user.

appvirality.getFriendsList(function (err, data) {

});

Get Friends List - Output Parameters

Parameters Explained

Parameter	Type	Decription
userbalance	Array<userbalance>	Array of user balance details
friends	Array<friends>	Array of friends
invitedfriends	Array<invitedfriends>	Array of friends invited by the user
totalfriends	int	Array of user balance details
convertedfriends	int	Array of user balance details
success	boolean	True, if API call was successful else False
message	String	Message from the server, if required

userbalance Explained

Parameter	Type	Decription
rewardunit	String	Reward Unit for the balance
total	int	Total reward amount earned
claimed	int	Reward amount claimed
pending	int	Reward amount pending

friends Explained

Parameter	Type	Decription
userkey	String	Friend’s unique identifier
useraccountid	String	Friend’s account identifier
email	String	Friend’s email address
status	String	Friend’s current status with the app, ex SignUp, Converted, etc.
name	String	Name of the Friend
profileimage	String	Friend’s profile image URL
regdate	String	Friend’s registration date
earnedrewards	Array<earnedrewards>	Reward amount pending
isremind	boolean	True, if user can remind his friend else False

earnedrewards Explained

Parameter	Type	Decription
eventname	String	Reward event name
reward	String	Amount of reward
rewardunit	String	Unit of the reward
rewardedon	String	Date on which rewarded
rewardstatus	String	Status of the reward, i.e. Approved, Rewarded, etc
rewardtype	String	Reward Type, i.e. Coupon, InstoreCredit, etc
usertype	String	User type, i.e. Referrer or Friend
coupon	String	Rewarded coupon’s code
campaignid	String	Identifier of the campaign for which rewarded
campaignname	String	Name of the campaign for which rewarded
growthhack	String	Name of the growth hack for which rewarded
couponimage	String	Coupon’s Image URL
coupondetails	String	Coupon description
couponname	String	Name of the coupon pool
friendemail	String	Friend’s email address
friendname	String	Friend’s name
friendprofileimage	String	Friend’s profile image URL

invitedfriends Explained

Parameter	Type	Decription
friendemail	String	Friend’s email address
regdate	String	Friend’s registration date
isremind	boolean	True, if user can remind his friend else False

Get Code

This callback is used to retrieve the referrer’s referral code.

appvirality.getReferrerCode(appkey, function (err, data) {

});

Get Code - Output Parameters

Parameters Explained

Parameter	Type	Decription
referrercode	String	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.

appvirality.validateCode(referralCode, function (err, data) {

});

Validate Code - Input Parameters

Parameter	Type	Description
referralCode	String	Referrer’s referral code

Validate Code - Output Parameters

Parameter	Type	Description
success	boolean	True, if the referral code is valid else False
message	String	Message from the server, if required

Apply Code

This callback is used to apply referral code for a user, to confirm the referrer.

appvirality.applyCode(referralCode, function (err, data) {

});

Apply Code - Input Parameters

Parameter	Type	Description
referralCode	String	Referrer’s referral code

Apply Code - Output Parameters

Parameter	Type	Description
success	boolean	True, if the referral code applied successfully else False
message	String	Message from the server, if required

Get Referrer

This callback is used to retrieve the referrer details.

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

});

Get Referrer - Input Parameters

Parameter	Type	Description
appkey	String	App key provided by AppVirality > Dashboard > AppDetails
referrercode (optional)	String	Invite code used by the user during signup/subscription
useremail (optional)	String	Email of the current user for whom you want to get the referrer details
useraccountid (optional)	String	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)

Get Referrer - Output Parameters

Parameter	Type	Description
referrercode	String	Referrer code of the user
referrername	String	Referrer name
profileimage	String	Profile image url of the referrer
friendreward	String	Current on boarding user reward
friendrewardunit	String	unit of the friend reward, like $ or %
friendrewardfrequency	String	reward duration, i.e. 3 months or 6 months
hasreferrer	boolean	‘True’ if the user has referrer when you invoke the call with user email
isexistinguser	boolean	‘True’ if the user already registered when you invoke the call with user email
userkey	String	Unique id generated by AppVirality for each registered user
success	boolean	‘True’ if the API success
message	String	Any message from server if required

This callback is used to display the Referral Widget to be used for referring a friend.

appvirality.widget(
    {
    title: 'Demo App',
    description: 'AppVirality Demo app!',
    iframe: true
    }
);