|
|
| |
|
|
|
iOS Tutorial
Getting Started
Step 2: Install the iOS SDK
Before you begin development with the AGE iOS SDK, you will need to install the iOS development tools and download the AGE SDK.
To install the SDK, copy all files under AppGrowthEngine/SDKClasses to your XCode project. You should also copy over the SBJson library files if your application does not already have them (e.g., if you use the Facebook iOS SDK, you would already have SBJson). In addition, you need to add the following two iOS SDK frameworks to your project as dependencies:
- AddressBook.framework
- MessageUI.framework
Step 3: Use the iOS SDK
Once you have created an application, you can start the SDK in your application delegate with the app key you have registered. You can also stop the SDK when you exit the application.
- (BOOL)application :(UIApplication *)application didFinishLaunchingWithOptions :(NSDictionary *)launchOptions { [HKMDiscoverer activate:@"Your-App-Key"]; // ... ... } - (void)applicationWillTerminate:(UIApplication *)application { [HKMDiscoverer retire]; }
The usage of the SDK is illustrated in the sample application. Just open the XCode project, fill in the app key in the SampleAppDelegate class, and run the project (ideally in a physical iPhone attached to the dev computer). The buttons in the sample demonstrate key actions you can perform with the SDK.
Device Verfication
Step 1: Send Confirmation Code
By calling the following SDK method, you can create an in-app SMS message box for the app user to send an confirmation message so that you can capture their phone number.
[[HKMDiscoverer agent] verifyDevice:myViewController forceSms:NO userName:@"John Doe"];
The SMS message screen is displayed as a modal view controller on top of the myViewController screen. The forceSms parameter indicates whether the user can cancel the SMS screen without sending the confirmation message. If it is set to YES, the user would have to send out the confirmation. The userName parameter takes the user's name. You can leave this to nil if you have not collected name from your user.
Step 2: Query Status
Once the user sends out the confirmation, you can query their confirmation status via the following call. Note that the call returns immediately and performs the confirmation in the background. Your application code needs to listen for HookDeviceVerified or HookDeviceVerified in NSNotificationCenter in order to receive the confirmation results.
[[HKMDiscoverer agent] queryVerifiedStatus]; ... ... - (void)viewDidLoad { ... ... [[NSNotificationCenter defaultCenter ] addObserver :self selector :@selector(verificationStatusYes ) name :@"HookDeviceVerified" object :nil]; [[NSNotificationCenter defaultCenter ] addObserver :self selector :@selector(verificationStatusNo ) name :@"HookDeviceNotVerified" object :nil]; }
Smart Invitation
Step 1: Discover
To get a list of contacts from user's addressbook that are most likely to install your app, you need to execute a discovery call like this first. The call returns immediately, and processes the discovery in background.
[[HKMDiscoverer agent] discover];
Step 2: Get Recommended Invites
It takes Hook Mobile seconds to determine the devices for each of the phone numbers, and come up with an optimized list.
Once complete issue the following call. Again, the call returns immediately, and you should listen for the HookQueryOrderComplete event.
When the HookQueryOrderComplete event is received, you can query a list of Leads, which contains phone numbers and device types.
[[HKMDiscoverer agent] queryLeads]; - (void)viewDidLoad { ... ... [[NSNotificationCenter defaultCenter ] addObserver :self selector :@selector(queryComplete ) name :@"HookQueryOrderComplete" object :nil]; } - (void) queryComplete { [self.navigationController pushViewController:leadsController animated:YES]; } - (UITableViewCell *)tableView :(UITableView *)tableView cellForRowAtIndexPath :(NSIndexPath *)indexPath { UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"Leads"]; ... ... cell.textLabel.text = ((Lead *)[[HKMDiscoverer agent].leads objectAtIndex:indexPath.row]).phone; cell.detailTextLabel.text = ((Lead *)[[HKMDiscoverer agent].leads objectAtIndex:indexPath.row]).osType; return cell; }
Now, you can prompt your user to send personal invites to their friends in [[HKMDiscoverer agent].leads to maximize the chance of referral success!
Step 3: Send Invitations
The AGE platform enables you to track the performance of your referrals via customized URLs that you can use in invite messages. The newReferral method creates a referral message with the custom URL.
[[HKMDiscoverer agent] newReferral:phones withMessage:@"I thought you might be interested in this app 'AGE SDK', check it out here %link% " useVirtualNumber:YES ];
The phones parameter is an NSArray that contains a list of phone numbers you wish to send referrals to.
It is typically a list selected from the leads returned by [[HKMDiscoverer agent].leads.
The withMessage parameter takes a message template with %link% referring to customized referral URL from the AGE platform.
The useVirtualNumber option specifies whether AGE should send out the referrals via its own virtual number.
If not, the application itself is responsible for letting the user send out the referrals via their own devices.
Once the AGE server returns, the SDK raises the HookNewReferralComplete notification and you can retrieve the referral message from [HKMDiscoverer agent].referralMessage. Then, you can prompt the user of your app to send that referral message via SMS. NOTE: if your device is not an SMS device (e.g., a WIFI iPad or an iPod Touch), the AGE server will send out the referral message automatically, and hence removing the need for the app to retrieve and send the [HKMDiscoverer agent].referralMessage.
- (void)viewDidLoad { ... ... [[NSNotificationCenter defaultCenter ] addObserver :self selector :@selector(showReferralMessage ) name :@"HookNewReferralComplete" object :nil]; } - (void) showReferralMessage { ... ... if ([MFMessageComposeViewController canSendText]) { MFMessageComposeViewController *controller = [[[MFMessageComposeViewController alloc] init] autorelease]; controller.body = [HKMDiscoverer agent].referralMessage; controller.recipients = phones; controller.messageComposeDelegate = self; [self presentModalViewController:controller animated:YES]; } else { [self.navigationController popViewControllerAnimated:YES]; } }
Optionally, you could also tell AGE that the user have sent the invitation messages. That helps AGE better correlate the installation statistics for you.
- (void)messageComposeViewController:(MFMessageComposeViewController *)controller didFinishWithResult:(MessageComposeResult)result { [self dismissModalViewControllerAnimated:YES]; if (result == MessageComposeResultCancelled) { [[HKMDiscoverer agent] updateReferral:NO]; } else { [[HKMDiscoverer agent] updateReferral:YES]; } [self.navigationController popViewControllerAnimated:YES]; }
Tracking Referrals and Installs
Step 1: Track Your Referrals
The AGE API also allows you to track all referrals you have sent from any device, and get the referrals' click throughs. This makes it possible for you to track referral performance of individual devices, and potentially reward the users who generate the most referral click through.
[[HKMDiscoverer agent] queryReferral];
Once the referral data is retrieved from the AGE server, the SDK generates a notification event HookQueryReferralComplete. The referral data is stored in the [HKMDiscoverer agent].referrals array with each HKMReferralRecord element in the array representing a referral.
@interface HKMReferralRecord : NSObject { int totalClickThrough; int totalInvitee; }
Step 2: Track Friends Who Install The Same App
The AGE platform allows you to find friends who also install the same app from your addressbook. To query for friends installs in your addressbook, you must call the discover method first. And then, you can call the queryInstalls. This method takes a string parameter that indicates how the searching and matching of addressbook should be done.
FORWARD - Find contacts within your address book who has the same app.
BACKWARD - Find other app users who has your phone number in their address book. When to use this? When the app wants to suggest a long lost friend who has your contact, but not vice versa.
MUTUAL - Find contacts within your address book who has the same app and who also has your contact in his/her address book. This query may be useful for engaging a friend to play in multi-player game who already plays the game.
Below is an example:
[[HKMDiscoverer agent] queryInstalls:@"FORWARD"];
Once the SDK receives the friends who have the same app, it generates a HookQueryInstallsComplete notification and saves the results in an array of HKMLead objects in [HKMDiscoverer agent].installs.
|
| |
|
|
