Callbacks

The AppVirality SDK 2.0 for Android 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)
• Get Campaigns
• Update User Info
• Save Conversion Event
• Submit Referral Code
• Get Campaign Terms
• Customize Referral Code
• Check Attribution
• Get User Balance
• Get User Rewards
• Get User Coupons
• Get Coupon Pools
• Redeem Coupon
• Get Friends
• Referrer Details Ready
• Product Attribution

AppVirality Initialization (Init)

Initialize the SDK

---

This callback is used while initializing the AppVirality SDK.
Initializing the SDK is critical to loading of the growth hacks & 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
• Reward type for the user etc.

Below code block is how it is implemented:

appVirality.init(userDetails, new AppVirality.AppViralitySessionInitListener() {
    @Override
    public void onInitFinished(boolean isInitialized, JSONObject responseData, String errorMsg) {
        Log.i("AppVirality: ", "InitWithAppKey Status " + isInitialized);
        if (responseData != null)
            Log.i("AppVirality: ", "userDetails " + responseData.toString());
    }
});

Input Params

Input Params	Description
userDetails UserDetails	Used to set the user details for initialization
appViralitySessionInitListener AppViralitySessionInitListener	To grasp & capture the callback upon initialization API execution

Response Params

Output Params	Description
isInitialized boolean	True, if the SDK gets initialized successfully; else False
responseData JSONObject	Carries user info: referrer, friends, reward info, etc.
errorMsg String	Error message, if the initialization fails; else NULL

responseData : Elaborated

responseData JSON contains initialization related data.

Parameters Explained

Parameter	Type	Description
userKey	String	Unique key to identify a user
customDomain	String	Custom Domain Name if your app has a custom domain. For Ex, refer.mydomain.com
isExistingUser	boolean	TRUE, if the user already exists else FALSE
hasReferrer	boolean	TRUE, if the user has a referrer else FALSE
referrerCode	String	Referrer’s referral code
referrerName	String	Referrer’s Name
profileImage	String	Referrer’s profile image URL
rewardType	String	Tells who gets the reward. Can have values as 1, 2 or 3 for Only Referrer, Only Friend, Referrer and Friend both respectively
friendReward	String	Reward amount for Friend
friendRewardUnit	String	Reward Unit for Friend’s reward
friendRewardEvent	String	Event for which Friend shall get the reward
friendIncentiveDesc	String	Description for the Friend reward
welcomeMessage	String	Welcome Message to be shown to the new user acquired through referral
offerTitleColor	String	Color code for the offer title set as set on dashboard
offerDescriptionColor	String	Color code for the offer description as set on dashboard
campaignBGColor	String	Color code for the background as set on dashboard
attributionSetting	String	Attribution Setting as set for your campaign. Can have values as 0, 1 or 2 for Only Referral Link, Referral Link & Referral Code both, Only Referral Code respectively
isReferrerConfirmed	boolean	TRUE, if referrer has been confirmed for the user else FALSE
isNewSession	boolean	TRUE, if a new session is started
success	boolean	TRUE, if the initialization was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Provided Click ID is Invalid	Click ID sent in API is invalid
Referrer is not Eligible to Participate in Campaign	Referrer is not eligible to participate in campaign. For ex, Referral Code belongs to a campaign which is in Paused or Draft state currently
Existing User - Provided IMEI already exists	User’s device IMEI already exists in the system
Is an Existing User	User already exists in the system
Referrer Code doesn’t exists	Referral code supplied in the API doesn’t exists in the system
Existing User - Provided UserKey already exists	User Key supplied in Register API already exists in the system.
Existing User - Provided Email already exists	Email address provided during SDK initialization already exists in the system
Existing User - Provided Email already exists on another Device	Email address provided during SDK initialization already exists on another device
Existing User - Provided Device already exists	Device already exists in the system
Existing User - Provided Email & Device already exists	Provided Email address and Device already exists in the system
Existing User - Provided Device Advertising ID already exists	Provided device advertising ID already exists in the system
Referrer registered date is after Friend Registered Date	Referrer has registered after Friend, hence attribution can’t happen
AppVirality API Key cannot be null. Make sure you have provided the API Key in the Manifest	API Key is not provided in the manifest
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Get Campaigns

Gets you all the details of active campaigns eligible for a user

---

This callback is used to get a list of all the active campaigns details like campaignId, campaignName, growthHackType, etc.

This callback is critical to preparing the Campaign inside a user’s app. Based on the applicable campaign, and if it is available in the active campaign array (returned in this callback) - you can go ahead and refresh the images required for those campaigns specifically.

appVirality.getCampaigns(growthHackType, new AppVirality.CampaignDetailsListener() {
    @Override
    public void onGetCampaignDetails(ArrayList<CampaignDetail> campaignDetails, boolean refreshImages, String errorMsg) {

}
});

Input Params

Input Params	Description
growthHackType enum	A constant for denoting the growth hack type for which you want to get campaign details e.g. Constants.GrowthHackType.Word_of_Mouth, Constants.GrowthHackType.Loyalty_Program, etc
campaignDetailsListener CampaignDetailsListener	To capture the callback for obtaining the campaign details

Response Params

Output Params	Description
campaignDetails ArrayList<CampaignDetail>	Array list of CampaignDetail class objects, which contains various campaign related data like campaignId, campaignTitle, etc.
refreshImages boolean	True, if Word of Mouth campaign details are changed ; else False Imp Note: You must download all the Word of Mouth campaign images whenever you get this as True, as it would be provided only once on campaign details change
errorMsg String	Error message, if the GetCampaign API call gets failed ; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Exception while parsing response data.	Code threw exception while parsing the GetCampaign API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Update User Info

Used while updating user details or info like name, image, etc

---

This must be executed in conjunction with the “/updateappuserinfo” API call to update a user’s details or information.

appVirality.updateAppUserInfo(userDetails, new AppVirality.UpdateUserInfoListener() {
    @Override
    public void onResponse(boolean isSuccess, String errorMsg) {

}
});

Input Params

Input Params	Description
userDetails UserDetails	Sets the various user details which you want to update using its setter methods
updateUserInfoListener UpdateUserInfoListener	It gets/grasps the data from the ‘updateappuserinfo’ API response

Response Params

Output Params	Description
isSuccess boolean	True, if the user info updated successfully ; else False.
errorMsg String	Error message, if the API call gets failed ; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
‘UserDetails’ is null.	UserDetails object provided for updating the user info is null
You have no active campaigns at this moment.	No active campaigns are available for the app

Save Conversion Event

Used in conjunction with the “/saveconversionevent” API to register/save an event’s occurrence

---

This callback is used while saving a conversion event using the “/saveconversionevent” API request.

appVirality.saveConversionEvent(event, transactionValue, transactionUnit, campaignId, growthHackType, new AppVirality.ConversionEventListener() {
    @Override
    public void onResponse(boolean isSuccess, String message, String errorMsg) {
        Toast.makeText(getApplicationContext(), message, Toast.LENGTH_LONG).show();
    }
});

Input Params

Input Params	Description
event String	Name of the Event to be saved, i.e. Install || Signup || Transaction || Any Defined Custom Event
transactionValue String	Amount of transaction if applicable for the event, else NULL
transactionUnit String	Unit of the transactionValue if applicable for the event, else NULL
growthHackType enum	A constant for denoting the growth hack type for which you want to get campaign details e.g. Constants.GrowthHackType.Word_of_Mouth, Constants.GrowthHackType.Loyalty_Program, etc.
conversionEventListener ConversionEventListener	To get/grasp the data obtained as response from the ‘saveconversionevent’ API request

Response Params

Output Params	Description
isSuccess boolean	True, if user got any reward for the event ; else False
message String	Message to display if API call is successful
errorMsg String	Error message, if the API call gets failed ; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Event name not given.	Name of the event to be recorded not given
You have no active campaigns at this moment.	No active campaigns are available for the app

Submit Referral Code

Used to receive & consume the Referral Code, when applied by a Friend

---

A new user i.e. a Friend, while signing up might be prompted to enter the Referral Code. When the code is entered, it must be consumed and the attribution to the Referrer must follow thereafter.
The code is consumed and the “/setreferrercode” API call gets executed hereafter. Use this callback only if the attribution has not happened already from Referral Link.

This callback handles all of that!

appVirality.submitReferralCode(referralCode, new AppVirality.SubmitReferralCodeListener() {
    @Override
    public void onResponse(boolean isSuccess, JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
referralCode String	Referral code of the referrer. It can contain characters from a-z, A-Z, 0-9, or - only.
submitReferralCodeListener SubmitReferralCodeListener	To catch/grasp the response data from the setreferrercode API call

Response Params

Output Params	Description
isSuccess boolean	True, if the referral code applied successfully ; else False
responseData JSONObject	Submit Referral Code API response data
errorMsg String	Error message, if the API call gets failed ; else NULL

responseData : Elaborated

responseData JSON contains referrer and campaign related details.

Parameters Explained

Parameter	Type	Description
userKey	String	Unique key to identify a user
customDomain	String	Custom Domain Name if your app has a custom domain. For Ex, refer.mydomain.com
isExistingUser	boolean	TRUE, if the user already exists else FALSE
hasReferrer	boolean	TRUE, if the user has a referrer else FALSE
referrerCode	String	Referrer’s referral code
referrerName	String	Referrer’s Name
profileImage	String	Referrer’s profile image URL
rewardType	String	Tells who gets the reward. Can have values as 1, 2 or 3 for Only Referrer, Only Friend, Referrer and Friend both respectively
friendReward	String	Reward amount for Friend
friendRewardUnit	String	Reward Unit for Friend’s reward
friendRewardEvent	String	Event for which Friend shall get the reward
friendIncentiveDesc	String	Description for the Friend reward
welcomeMessage	String	Welcome Message to be shown to the new user acquired through referral
offerTitleColor	String	Color code for the offer title set as set on dashboard
offerDescriptionColor	String	Color code for the offer description as set on dashboard
campaignBGColor	String	Color code for the background as set on dashboard
attributionSetting	String	Attribution Setting as set for your campaign. Can have values as 0, 1 or 2 for Only Referral Link, Referral Link & Referral Code both, Only Referral Code respectively
isReferrerConfirmed	boolean	TRUE, if referrer has been confirmed for the user else FALSE
success	boolean	TRUE, if the API call was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Referrer Code is his own code	Referral Code submitted is the user’s own referral code
Referrer is not Eligible to Participate in Campaign	Referrer is not eligible to participate in campaign. For ex, Referral Code belongs to a campaign which is in Paused or Draft state currently
Is an Existing User	User already exists in the system
Referrer Code doesn’t exists	Referral code supplied in the API doesn’t exists in the system
User Already Attributed	User is already attributed to some other referrer.
Referrer registered date is after Friend Registered Date	Referrer has registered after Friend, hence attribution can’t happen
Attribution Setting is set to Only Link. Referrer Code is not allowed	App’s attribution is Only Referral Link, means attribution can’t happen with Referral Code
Failed to apply Referral Code. Referral Code is empty.	Submitted referral is empty
Invalid Referral Code. Referral Code can contain characters from a-z, A-Z, 0-9 or - only.	Submitted referral code is in invalid format
Failed to apply Referral Code : User already attributed.	User is already attributed to some other referrer
Failed to apply Referral Code : Attribution setting is Only Referral Link.	App’s attribution is Only Referral Link, means attribution can’t happen with Referral Code
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Get Campaign Terms

Use this to obtain the Campaign Terms & Conditions

---

This callback allows you to get the set of Terms & Conditions for a campaign, as maintained in the AppVirality Dashboard against the particular campaign.

Ideally this simply grabs the response from the “/campaignterms” API request

appVirality.getCampaignTerms(campaignId, new AppVirality.CampaignTermsListener() {
    @Override
    public void onGetCampaignTerms(String terms, String errorMsg) {

}
});

Input Params

Input Params	Description
campaignId String	Campaign ID of the campaign whose terms you want to fetch
campaignTermsListener CampaignTermsListener	To grab the response received from the campaignterms API call

Response Params

Output Params	Description
terms String	Campaign terms, if terms are set on dashboard ; else NULL
errorMsg String	Error message, if the API call gets failed ; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Invalid CampaignID	Campaign ID for which terms are requested is invalid
Campaign Id not given.	Campaign ID for which terms are requested is not provided
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Customize Referral Code

Applicable when the user initiates a request to customize his/her Referral Code

---

When the user would choose to customize his referral code, then this particular callback shall come in play.

This simply plays along to accommodate and grab the response from customizereferralcode API request.

appVirality.customizeReferralCode(referralCode, new AppVirality.CustomizeRefCodeListener() {
    @Override
    public void onCustomRefCodeSet(boolean isSuccess, String errorMsg) {
        try {

} catch (Exception e) {
        }
    }
});

Input Params

Input Params	Description
referralCode String	New Referral Code. It can contain characters from a-z, A-Z or 0-9 only, with a maximum length of 10 characters.
customizeRefCodeListener CustomizeRefCodeListener	Grabs/consumes the response from customizereferralcode API call

Response Params

Output Params	Description
isSuccess boolean	True, if referral code is customized successfully; else False
errorMsg String	Error message, if the API call gets failed ; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Referrer Code already exists	Provided referral code is same as the current referral code
Empty Referral Code.	Provided referral code is empty
Invalid Referral Code. Referral Code can contain characters from a-z, A-Z or 0-9 only.	Provided referral code format is invalid
You have no active campaigns at this moment.	No active campaigns are available for the app

Check Attribution

Runs a check to ascertain whether a user has been attributed to a Referrer

---

This callback is used to check the attribution status for a user, it returns the user and referrer data in the callback.

This method can be used to check if the user is an existing user, referred user, etc.

appVirality.checkAttribution(referrerCode, new AppVirality.CheckAttributionListener() {
    @Override
    public void onResponse(JSONObject responseData, String errorMsg) {
        try {
            if (responseData != null){
                if (responseData.getBoolean("isExistingUser")){
                    // User already exists
                } else {
                     // Its a new user
                }
            }
        }
        catch (Exception e) {

}
    }
});

Input Params

Input Params	Description
referrerCode	(optional) Friend’s Referral code provided by user
checkAttributionListener CheckAttributionListener	Grabs/consumes the response to the callback - as it returns the user & referrer details

Response Params

Output Params	Description
referrerDetails JSONObject	User and Referrer details
errorMsg String	Error message, if any error occurs while checking the attribution status; else NULL.

responseData : Elaborated

referrerDetails JSON contains referrer and other campaign related details.

Parameters Explained

Parameter	Type	Description
userKey	String	Unique key to identify a user
isExistingUser	boolean	TRUE, if the user already exists else FALSE
hasReferrer	boolean	TRUE, if the user has a referrer else FALSE
referrerCode	String	Referrer’s referral code
referrerName	String	Referrer’s Name
profileImage	String	Referrer’s profile image URL
rewardType	String	Tells who gets the reward. Can have values as 1, 2 or 3 for Only Referrer, Only Friend, Referrer and Friend both respectively
friendReward	String	Reward amount for Friend
friendRewardUnit	String	Reward Unit for Friend’s reward
friendRewardEvent	String	Event for which Friend shall get the reward
friendIncentiveDesc	String	Description for the Friend reward
userEmail	String	User’s Email Address
welcomeMessage	String	Welcome Message to be shown to the new user acquired through referral
offerTitleColor	String	Color code for the offer title set as set on dashboard
offerDescriptionColor	String	Color code for the offer description as set on dashboard
campaignBGColor	String	Color code for the background as set on dashboard
isRewardExists	boolean	Tells if friend can earn reward through Install event
attributionSetting	String	Attribution Setting as set for your campaign. Can have values as 0, 1 or 2 for Only Referral Link, Referral Link & Referral Code both, Only Referral Code respectively
isReferrerConfirmed	boolean	TRUE, if referrer has been confirmed for the user else FALSE

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Provided Click ID is Invalid	Click ID provided in the API request is invalid
Provided Click ID is Invalid
Referrer is not Eligible to Participate in Campaign	Referrer is not eligible to participate in campaign. For ex, Referral Code belongs to a campaign which is in Paused or Draft state currently
Existing User - Provided IMEI already exists	User already exists, as the system already contains the device’s IMEI
Referrer Code doesn’t exists	Provided referral code doesn’t exist in the system
Existing User - Provided Device already exists	Existing user, as the device already exists in the system
Existing User - Provided Device Advertising ID already exists	Existing user, as the device’s advertising ID already exists in the system
Referrer registered date is after Friend Registered Date	Referrer has registered after Friend, hence attribution can’t happen
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Get User Balance

To get the user balance

---

When requesting/pulling out the users’ balances and credits for the app promotions, this callback does the needful.

It simply triggers & consumes the results from the execution of the getuserbalance API.

This callback is critical to your app’s Earnings display activity. The response data obtained would contain all the credits/earnings of the user - be it Coupon or Wallet credit. Each reward shall be nested under the respective growth hack type i.e. Loyalty, Word Of Mouth (Referrals), etc.

appVirality.getUserRewardDetail(campaignId, new AppVirality.UserBalanceListener() {
    @Override
    public void onGetRewardDetails(JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
campaignId String	Campaign ID for which to get the user balance.
userBalanceListener UserBalanceListener	To grab/consume the response from the getuserbalance API call

Response Params

Output Params	Description
responseData JSONObject	Contains all rewards related data for a user i.e. claimed, pending, etc.; amount, coupon code, gross amount earned, etc.
errorMsg String	Error message, if the API call gets failed ; else NULL

responseData : Elaborated

responseData JSON contains user balance details.

Parameters Explained

Parameter	Type	Description
userBalance	JSONObject	Contains user balance JSON data
total (userBalance ->)	int	Total user balance earned
claimed (userBalance ->)	int	Total balance claimed by the user
pending (userBalance ->)	int	Total pending balance
approved (userBalance ->)	int	Total approved balance available to redeem
growthHacks (userBalance ->)	JSONArray	Growth hack wise user balance break-up
ghName (userBalance -> growthHacks ->)	String	Growth hack name for which earned reward
total (userBalance -> growthHacks ->)	int	Total balance earned for a growth hack
claimed (userBalance -> growthHacks ->)	int	Balance claimed from a growth hack earnings
pending (userBalance -> growthHacks ->)	int	Balance pending for a growth hack
approved (userBalance -> growthHacks ->)	int	Approved balance for a growth hack, available to redeem
campaigns (userBalance -> growthHacks ->)	JSONArray	Campaign wise user balance break-up
campaignId (userBalance -> growthHacks -> campaigns ->)	int	Identifier for the campaign
campaignName (userBalance -> growthHacks -> campaigns ->)	String	Name of the campaign
total (userBalance -> growthHacks -> campaigns ->)	int	Total balance earned for a campaign
claimed (userBalance -> growthHacks -> campaigns ->)	int	Balance claimed from a campaign earnings
pending (userBalance -> growthHacks -> campaigns ->)	int	Balance pending for a campaign
approved (userBalance -> growthHacks -> campaigns ->)	int	Approved balance for a campaign, available to redeem
rewardUnit (userBalance -> growthHacks -> campaigns ->)	String	Reward unit for a campaign
success	boolean	TRUE, if the API call was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Invalid CampaignID	Campaign ID provided in the API request is invalid
You have no active campaigns at this moment.	No active campaigns are available for the app

Get User Rewards Detail

To get the user rewards detail

---

When requesting/pulling out the users’ rewards details and credits for the app promotions, this callback does the needful.

It simply triggers & consumes the results from the execution of the getuserrewards API.

This callback is critical to your app’s Earnings display activity. The response data obtained would contain all the credits/earnings of the user - be it Coupon or Wallet credit. Each reward shall be nested under the respective growth hack type i.e. Loyalty, Word Of Mouth (Referrals), etc.

appVirality.getUserRewards(growthHackType, campaignId, new AppVirality.UserRewardsListener() {
    @Override
    public void onResponse(JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
growthHackType enum	Type of growth hack for which getting the rewards data. Ex, Constants.GrowthHackType.Word_of_Mouth, Constants.GrowthHackType.Loyalty_Program, etc.
campaignId String	Campaign ID for which to get the reward data.
userRewardsListener UserRewardsListener	To grab/consume the response from the getuserrewards API call

Response Params

Output Params	Description
responseData JSONObject	Contains detail reward data for a user.
errorMsg String	Error message, if the API call gets failed ; else NULL

responseData : Elaborated

responseData JSON contains details about all the rewards earned by the user.

Parameters Explained

Parameter	Type	Description
rewards	JSONArray	Contains user rewards
name (rewards ->)	String	Name of the user who earned the reward
image (rewards ->)	String	Image URL of the user who earned the reward
email (rewards ->)	String	Email of the user who earned the reward
reward (rewards ->)	String	Reward Amount earned
rewardUnit (rewards ->)	String	Reward unit for the amount earned
rewardedOn (rewards ->)	String	Date on which rewarded
eventName (rewards ->)	String	Event name for which rewarded
rewardStatus (rewards ->)	String	Reward status i.e. Rewarded/Rejected/Suspicious/Pending
rewardType (rewards ->)	String	Reward type i.e. Coupons/Instore Credits
userType (rewards ->)	String	User type i.e. Friend/Referrer/LoyaltyUser
coupon (rewards ->)	String	Coupon Code
campaignID (rewards ->)	String	Campaign identifier under which earned reward
campaignName (rewards ->)	String	Campaign name under which earned reward
growthhack (rewards ->)	String	Growth hack name under which earned reward
couponimage (rewards ->)	String	Coupon Pool Image URL
coupondetails (rewards ->)	String	Coupon Pool description
couponname (rewards ->)	String	Coupon Pool Name
success	boolean	TRUE, if the API call was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Invalid GrowthHack	GrowthHack type provided in the API request is invalid
Invalid CampaignID	Campaign ID provided in the API request is invalid
Empty Referral Code.	Provided referral code is empty
Invalid Referral Code. Referral Code can contain characters from a-z, A-Z or 0-9 only.	Provided referral code format is invalid
You have no active campaigns at this moment.	No active campaigns are available for the app

Get User Coupons

Use this to get the list of coupons tagged to a particular user at any given time

---

For handling the feature of displaying all the coupons tagged to a user, in case you have a coupon driven incentive schema for your app - this particular callback shall be employed.

Simply speaking it consumes the response data from the /getusercoupons API call and delivers it as a JSONArray.

Take note that this list of coupon details includes an individual image for each of these coupons, wherever applicable. This improves your scope for presenting these coupons to the end user, if you were to choose a custom display UI for the same - ignoring the one provided by AppVirality as default.

appVirality.getUserCoupons(new AppVirality.UserCouponsListener() {
    @Override
    public void onGetCoupons(boolean isSuccess, JSONArray userCoupons, String errorMsg) {

}
});

Input Params

Input Params	Description
userCouponsListener UserCouponsListener	Grabs/consumes the getusercoupons API call response

Response Params

Output Params	Description
isSuccess boolean	True, if API gets executed successfully; else NULL
userCoupons JSONArray	An array of user coupon data
errorMsg String	Error message, if the API call fails ; else NULL

responseData : Elaborated

userCoupons JSON contains array of coupon details rewarded to a user.

Parameters Explained

Parameter	Type	Description
couponCode	String	Coupon Code
couponExpiry	String	Coupon Expiry Date
couponValue	String	Coupon Value
couponUnit	String	Coupon Unit
campaignID	String	Identifier of the campaign under which rewarded coupon
campaignName	String	Name of the campaign under which rewarded coupon
image	String	Coupon Pool Image URL
details	String	Coupon Pool description
name	String	Coupon Pool Name

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Get Coupon Pools

Gets you the list (with detail) of the Coupon Pools a user can choose a reward from

---

AppVirality has the novelty of offering a system that enables your app to offer users an option to choose their desired coupon from a choice of Coupon Pools. This keeps things interesting for the users and allows them to have goals to achieve with respect to the growth campaigns you run, i.e. they may aspire for that BookMyShow or Amazon coupon that you have on the offer.

This particular feature is enabled using this callback, which basically talks with the getcouponpools API call and delivers the list of eligible coupon pools for a user, based on his/her rewards tally. Use this code block to achieve the same:

appVirality.getCouponPools(campaignId, new AppVirality.CouponPoolsListener() {
    @Override
    public void onGetCouponPools(JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
campaignId String	Campaign ID of the campaign whose terms you want to fetch
couponPoolsListener CouponPoolsListener	Grabs/consumes the response from getcouponpools API call

Response Params

Output Params	Description
responseData JSONObject	Contains all coupon pool related data for a campaign including coupon pool details
errorMsg String	Error message, if the API call fails; else NULL

responseData : Elaborated

responseData JSON contains coupon pool details for various campaigns.

Parameters Explained

Parameter	Type	Description
campaigns	JSONArray	Contains campaign wise coupon pools
campaignId (campaigns ->)	String	Identifier for the campaign
campaignName (campaigns ->)	String	Campaign Name
growthhack (campaigns ->)	String	Growth hack name for the campaign
pools (campaigns ->)	JSONArray	Coupon Pools for the campaign
poolId (campaigns -> pools ->)	String	Coupon Pool Identifier
name (campaigns -> pools ->)	String	Coupon Pool Name
details (campaigns -> pools ->)	String	Coupon Pool Description
image (campaigns -> pools ->)	String	Coupon Pool Image URL
value (campaigns -> pools ->)	String	Value of a coupon under the coupon pool
success	boolean	TRUE, if the API call was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
You have no active campaigns at this moment.	No active campaigns are available for the app

Redeem Coupon

Allows for the redeeming or rewarding of coupons for a user’s redemption request

---

Given the coupon pools allow users to choose their desired coupon variant for their stacked up rewards, it is only logical that a coupon redeemer logic shall be requisite next.

This callback does that job for you, as it executes the redeemrewards API call and redeems the appropriate coupon for the end user - finally delivering whether the coupon got redeemed or not along with an error message if applicable.

appVirality.redeemFromPool(poolId, new AppVirality.CouponRedeemListener() {
    @Override
    public void onResponse(boolean isRedeemed, String errorMsg) {

}
});

Input Params

Input Params	Description
poolId String	ID of the coupon pool from which a coupon shall be redeemed/rewarded
couponRedeemListener CouponRedeemListener	Grabs/consumes the response from the redeemrewards API call

Response Params

Output Params	Description
isRedeemed boolean	True, if the coupon redeemed successfully ; else False
errorMsg	_String _Error message, if the API call fails; else NULL

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
Invalid PoolID	Provided Coupon Pool ID is invalid
There are no coupons in the coupon pool	No coupons are there in the coupon pool for provided Pool ID
No reward for user	User doesn’t have any reward
Pool Id not given.	Pool Id from which to redeem has not been provided
Exception while parsing response data.	Code threw exception while parsing the API response
You have no active campaigns at this moment.	No active campaigns are available for the app

Get Friends

Delivers you the list of friends for a particular user

---

Most app referral programs out there do not really captivate the imagination of the user, and what a pity that is! If you were not really able to see whom you brought/introduced to the app, via the App Referral program & hence earned rewards for yourself - you are missing a major picture of the activity. Where else could you be motivated to do this? What will prompt you back to try referring more friends?

This callback returns you the list of friends a user may have brought onto the app, through their referral invite - simply by tapping on the /getfriendslist API call.

appVirality.getFriends(int pageIndex, int pageSize, GetFriendsListener getFriendsListener() {
    @Override
    public void onGetFriends(JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
pageIndex int	Page Index for which to fetch Friends data.
pageSize int	Page size, number of records to fetch per page.
getFriendsListener GetFriendsListener	Grabs/consumes the response from /getfriendslist API call

Response Params

Output Params	Description
responseData JSONObject	Contains the entire data related to the Friends Info for your Growth Campaign
errorMsg String	Error message, if the API call gets failed ; else NULL

responseData : Elaborated

responseData JSON contains user’s friends details.

Parameters Explained

Parameter	Type	Description
friends	JSONArray	Contains user’s friends details
appUserId (friends ->)	int	App-Identifier for the friend
emailId (friends ->)	String	Email address of the friend
name (friends ->)	String	Name of the friend
profileImage (friends ->)	String	Profile Image URL of the friend
regDate (friends ->)	String	Friend’s registration date
success	boolean	TRUE, if the API call was successful else FALSE
Message	String	Information regarding API call (if relevant)

errorMsg : Elaborated

errorMsg string contains error message for the API call.

Error Messages Explained

Error Message	Description
Invalid User Key	User Key provided in the API request is invalid
You have no active campaigns at this moment.	No active campaigns are available for the app

Referrer Details Ready

Delivers the referrer and user details - useful for personalizing user welcoming/on-boarding

---

This callback is typically important when you want to customize the on-boarding of a user, who’s been acquired via a Referral Invite. This delivers you details like:

• Referrer name
• Referral Code
• Incentive Amount & Unit
• Incentivization Event
• Welcome Message (as set on AppVirality Dashboard) etc.

appVirality.getReferrerDetails(new AppVirality.ReferrerDetailsReadyListener() {
    @Override
    public void onReferrerDetailsReady(JSONObject referrerDetails) {

}
});

Input Params

Input Params	Description
referrerDetailsReadyListener ReferrerDetailsReadyListener	Grabs/consumes the response to the callback from the SDK with the referrer details

Response Params

Output Params	Description
referrerDetails JSONObject	Referrer and User details

responseData : Elaborated

referrerDetails JSON contains referrer and other campaign related details.

Parameters Explained

Parameter	Type	Description
userKey	String	Unique key to identify a user
isExistingUser	boolean	TRUE, if the user already exists else FALSE
hasReferrer	boolean	TRUE, if the user has a referrer else FALSE
referrerCode	String	Referrer’s referral code
referrerName	String	Referrer’s Name
profileImage	String	Referrer’s profile image URL
rewardType	String	Tells who gets the reward. Can have values as 1, 2 or 3 for Only Referrer, Only Friend, Referrer and Friend both respectively
friendReward	String	Reward amount for Friend
friendRewardUnit	String	Reward Unit for Friend’s reward
friendRewardEvent	String	Event for which Friend shall get the reward
friendIncentiveDesc	String	Description for the Friend reward
userEmail	String	User’s Email Address
welcomeMessage	String	Welcome Message to be shown to the new user acquired through referral
offerTitleColor	String	Color code for the offer title set as set on dashboard
offerDescriptionColor	String	Color code for the offer description as set on dashboard
campaignBGColor	String	Color code for the background as set on dashboard
isRewardExists	boolean	Tells if friend can earn reward through Install event
attributionSetting	String	Attribution Setting as set for your campaign. Can have values as 0, 1 or 2 for Only Referral Link, Referral Link & Referral Code both, Only Referral Code respectively
isReferrerConfirmed	boolean	TRUE, if referrer has been confirmed for the user else FALSE

Product Attribution

Ascertains the attribution of a shared product to the user/referrer who shared

---

This callback is used to record the attribution for a shared product. It calls the /recordproductattribution API to attribute share to the user who shared the product.

appVirality.recordProductAttribution(clickId, new AppVirality.ProductAttributionListener() {
    @Override
    public void onResponse(JSONObject responseData, String errorMsg) {

}
});

Input Params

Input Params	Description
clickId String	Click Id from intent extras when someone clicks on the shared product deep link.
productAttributionListener ProductAttributionListener	Grabs/consumes the response from /recordproductattribution API

Response Params

Output Params	Description
responseData JSONObject	Contains product related data
errorMsg String	Error message, if any error for API request; else NULL

responseData : Elaborated

responseData JSON contains the shared product attribution details.

Parameters Explained

Parameter	Type	Description
productCode	String	Unique key to identify a user
extraInfo	JSONObject	Contains additional data sent while sharing the product
success	boolean	TRUE, if the API call was successful else FALSE

Request Error

---

In the above callbacks we are returning an error message in case the API call gets failed due to some reason. Below is a list of error messages returned in the callbacks upon failure and their description:

• Internet connection not available. - If the device doesn’t have a working internet connection.
• Http Connection timed out. - If the API call gets timed-out while trying.
• SDK not initialized. - If SDK is not initialized and the requested API request requires SDK to be initialized first.
• Bad Request. - If the server returns 400 response status code, means could not understand the request due to invalid syntax.
• Unauthorized Request. - If the the server returns 401 response status code, means the request requires user authentication.
• Forbidden Request. - If the the server returns 403 response status code, means server is reachable but could not execute the request.
• Request Not Found. - If the the server returns 404 response status code, means server could not find anything matching the Request-URI.
• Service Unavailable - If the the server returns (>=500) response status code.
• Some unknown error occurred. - If some unidentified error occurs.
• Http Connection timed out. - If the API call gets timed-out while trying.