Integration Steps

A comprehensive guide to integrating your iOS app with AppVirality’s iOS SDK.

Kindly use the same APPKEY for all platforms

If you have registered your Android Application already and want to run the same referral campaign on iOS App as well, do not register the app on AppVirality again, separately. Use the same App Key obtained from the initial registration.

Please keep in mind that the AppVirality iOS SDK is supported for iPhone simulator 5S (or higher), and iPhone 4s device (and higher). AppVirality iOS SDK supports iOS V6.0 and above.
Please contact us if you need support for lower versions.

Additionally, going forward, we shall be denoting the invitation or referral sender as ‘Referrer’ and the _receiver_or beneficiary as ‘Friend’

STEP 1: Getting Started

STEP 2: Import Header

STEP 3: Initialize

STEP 4: Getting Referrer Details

STEP 5: Show Growth Hack

Pre-requisites: Test Growth Hacks in iOS

STEP 6: Record Social Action

STEP 7: Record Conversion Event

STEP 8: Get User Balance

STEP 9: Set User Details

STEP 10: Logout

Important: Identifying EXISTING Users

STEP 1: Getting Started

---

Download the latest AppVirality iOS SDK from here.
Drop the “includes” folder and “libAppVirality.a” file into your project root.

STEP 2: Import Header

---

Import “AppVirality.h” the header file

  #import "AppVirality.h"

STEP 3: Initialize

---

Initializing the AppVirality SDK has to be done at the very beginning of your App i.e. at -application:didfinishlaunchingwithoptions: method in AppDelegate file.

  (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSSetUncaughtExceptionHandler(&onUncaughtException);

// Override point for customization after application launch.
    // Enable cookie based attribution to achieve 100% attribution accuracy
    [AppVirality attributeUserBasedonCookie:AppVirality_AppKey OnCompletion:^(BOOL success, NSError *error) {

NSDictionary * userDetails = nil;
        //if your App has login/logout and would like to allow multiple users to use single device, uncomment below lines
        [AppVirality enableInitWithEmail];
        userDetails = @{@"EmailId":@"USER-EMAIL-ID",@"ReferrerCode":@"REFERRER-CODE",@"isExistingUser":@"false",@"country":@"USER-COUNTRY"};
        // Init AppVirality SDK
        [AppVirality initWithApiKey:AppVirality_AppKey WithParams:userDetails OnCompletion:^(NSDictionary *referrerDetails,NSError*error) {

//NSLog(@"user key %@",[[NSUserDefaults standardUserDefaults] valueForKey:@"userkey"]);
            //NSLog(@"User has Referrer %@", referrerDetails);
        }];
    }];

return YES;
}

Replace “YOUR_APP_KEY” in the above code block, with your App key from your app’s dashboard. You can get your App key from AppVirality Dashboard → App Details page.

STEP 4: Getting Referrer Details

---

This is required if you want to show the welcome screen on the first App launch. You can get the referrer details by calling the below code block.

[AppVirality getReferrerDetails:^(NSDictionary *referrerDetails, NSError *error) {
            NSLog(@"ref details %@",referrerDetails);
        }];

STEP 5: Show Growth Hack

---

The following callback method will return the referral campaign details. Use the campaign details to show the referral screen to the App users.

campaignDetails includes the list of social actions configured on AppVirality Dashboard. Please use the array with name socialactions to get the social share messages and unique share links for each social action.

[AppVirality getGrowthHack:growthHack completion:^(NSDictionary *campaignDetails,NSError*error) {
                NSLog(@"growth hack details %@",campaignDetails);
        }];

growthHack - Type of growth hack i.e. to get referral campaign use “GrowthHackTypeWordOfMouth”

STEP 6: Record Social Action

---

Call the below method after successful completion of the social action. i.e after sharing on social media. This records the user social action.

[AppVirality recordSocialActionForGrowthHack:GrowthHackTypeWordOfMouth WithParams:@{@"shareMessage":[[campaignDetails valueForKeyPath:@"socialactions.shareMessage"]firstObject],@"socialActionId":[[campaignDetails valueForKeyPath:@"socialactions.socialActionId"]firstObject],@"shortcode":[campaignDetails valueForKey:@"shortcode"]} completion:^(BOOL success,NSError*error) {
                        NSLog(@"social sucess %d",success);
                    }];

Social Action (Parameters)

Input Params

Input Params	Description
shareMessage	It is the message that the user has shared on social media
socialActionId	It is the user performed social action id, which can be obtained from campaign details

STEP 7: Record Conversion Event

---

Before recording any conversion event, please make sure to update the user details(at least EmailID) to AppVirality as noted/described in STEP 9. User details are critical to process rewards for the end user.

[AppVirality saveConversionEvent:@{@"eventName":@"Transaction",@"transactionUnit":@"Rs",@"transactionValue":@"560",@"extrainfo":@"orderid:78F6YG"} completion:^(NSDictionary *conversionResult,NSError *error) {
NSLog(@"conversion result %@",conversionResult);
}];

Conversion Event (Parameters)

Input Params

Input Params	Description
eventName	Name of the Reward rule configured on AppVirality Dashboard
transactionValue	Transaction amount. Example : 100
transactionUnit	The unit in which transaction was made. Example: $
extrainfo	Custom Info which is stored across the event and will be provided upon query of rewards. It is generally used to save transaction information which can be used to cross check later while rewarding. Extra Info is expected in encoded URI format.
Output Param	Description
Returns TRUE	On successful conversion i.e if this conversion event matches any of the reward rule configured on the dashboard

STEP 8: Get User Balance

---

This code block would give you the details about any user’s balance/earnings etc.

[AppVirality getUserBalance:self.growthHack completion:^(NSDictionary *userInfo,NSError*error) {
                self.userPoints = [(NSArray*)[userInfo valueForKey:@"userpoints"] firstObject];
                // List of friends installed through the referral link
                self.referredusers = [userInfo valueForKey:@"referredusers"];
                NSLog(@" user balance %@",userInfo);
        }];

Get User Balance (Parameters)

Input Params

Input Params	Description
userpoints	List of points
total	Total Rewards for that Campaign
claimed	Rewards claimed for that Campaign
redeemable_balance	Redeemable Balance i.e. rewards which met the review period and redemption cap
underreview	Rewards under review for that Campaign
rewardunit	Reward unit
redemptionthreshold	Redemption cap, it helps to let you know when to distribute the referrer reward

STEP 9: Set User Details

---

Please set the user details before calling “saveConversionEvent” in STEP 7 described above.

NSDictionary * userDetails = @{@"EmailId":@"mymail@test.com",@"AppUserName":@"CustomerName",@"ProfileImage":@"http://www.pics.com/profile.png",@"UserIdInstore":@"78903",@"city":@"Pune",@"state":@"Maharashtra",@"country":@"India",@"Phone":@"9876543210",@"isExistingUser":@"false",@"pushDeviceToken":@"YOUR-DEVICE-TOKEN"};

[AppVirality setUserDetails:userDetails Oncompletion:^(BOOL success, NSError *error) {
                NSLog(@"User Details update Status %d", success);
}];

Set User Details (Parameters)

Input Params

Input Params	Description
EmailId	Email id of the user
AppUserName	First name of the user, required to personalize the referral messages.
ProfileImage	User profile picture URL, required to personalize the referral messages
UserIdInstore	ID of the user in your App (helps to identify users on dashboard as you do in your app)
city	defines the city of the user
country	defines the country of the user
state	defines the state of the user location
Phone	contact number of the user
pushDeviceToken	User’s device push token to receive push notifications
isExistingUser	Set this as True, if you identify the user as existing user (this is useful if you don’t want to reward existing users).

STEP 10: Logout

---

Please call this method when user clicks on Logout in your App. This will clear the current user session to allow new user login to the App

    [AppVirality logout];

---

Identifying EXISTING Users

Set isExistingUser property as TRUE only on first App launch i.e. only once.

On subsequent launches please don’t set this property.

At any point of time, excluding the first time, if you set this property to TRUE all the existing user rewards will be set to Rejected state and also stops reward on future events.

Use this property carefully and with caution!

Integration Complete

Use the Sample Application to see the above callbacks in action.