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:

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
errorMsg : Elaborated

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, campaignNamegrowthHackType, 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

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

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

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
errorMsg : Elaborated

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

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

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
errorMsg : Elaborated

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
errorMsg : Elaborated

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
errorMsg : Elaborated

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
errorMsg : Elaborated

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
errorMsg : Elaborated

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

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
errorMsg : Elaborated

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

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
 


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.
Was this article helpful to you? Yes No