Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

An SDK for adding your PunchTab rewards program to your iOS mobile app

branch: master
readme.md

PunchTab iOS SDK

What is the PunchTab iOS SDK?

The PunchTab iOS SDK enable you to bring your customized loyalty and reward programs to your mobile apps. It is a static library that has been compiled as a "fat" binary for both iOS devices and the iOS Simulator. If you have any issues, please send them to ios@punchtab.com.

Note: Version 2.x of the SDK requires you to target iOS 5.0+ as it uses ARC and blocks. If you want an SDK that targets iOS 3.0+, try using the 1.x SDK.

Integrating the PunchTab SDK into your project

  1. Go to http://www.github.com/PunchTab/punchtab-ios-sdk and either download the package, or clone the git repository.
  2. Include the PTSDK.framework in your project.
  3. If you are going to be creating your own network stack with AFNetworking or JSONKit, please use the framework in the base directory. You must include these dependencies (AFNetworking and JSONKit) in your project either manually or with Cocoapods. If you want us to handle the dependencies for you, use the framework in the Framework+Dependencies directory.
  4. The PTSDK framework requires additional frameworks. Go to your project's Build Phases and choose Link Binaries With Libraries Add these frameworks:
    • QuartzCore

SDK Usage

Before you get started, you'll need to get a Client ID from punchtab.com

Simple interface

The PTController class is the only interface to the SDK. Import the PTController.h class anywhere you will be needing access to the SDK.

#import "PTController.h"

You can instantiate a PTController anywhere you want, but the UIApplicationDelegate subclass for your app will need access to it if you're going to use PunchTab sign-on.

PunchTab sign-on

Use PunchTab sign-on if you want PunchTab to handle user authentication for you.

    myPTController = [[PTController alloc] initWithClientId:@"123456"];

The PunchTab SDK uses Safari in order to authenticate the user. When you call the login method, the user will be directed out of the app to Safari. After the user signs in and gives your app permission, the user will be redirected back to your app where you'll get a login response.

If the user has previously logged into PunchTab either by browsing Safari, or through another application that has incorporated the PunchTab SDK, the user will not have to login to PunchTab again, and has only to give your app permission to continue.

For this to work, you'll need to implement this method in your UIApplicationDelegate subclass:

    - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {

        return [myPTController handleOpenURL:url];
    }

If you're using other shared or single sign-on SDKs in your app, like the Facebook SDK, you may already have this method implemented, but will want to modify it to look something like this:

    - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {

        return ([myPTController handleOpenURL:url] || [myFacebook handleOpenURL:url]);
    }

Lastly, in your app's Info.plist, add a key for URLTypes and a subItem of that called URLSchemes. Add an item with the format ptsdk<your punchtab Client ID>. i.e. ptsdk12345

Frameworks

Single sign-on (SSO)

Use SSO if you have your own authentication system and you want to pass a user to PunchTab to authorize.

    myPTController = [[PTController alloc] initWithClientId:@"123456" domainName:@"http://www.yourdomain.com" accessKey:@"Your access key" secretKey:@"Your secret key"]

Common requests

Response blocks

In order to get the responses for your requests, you will use blocks. All response blocks will contain two arguments: 1) A success boolean notifying you if the request was successful and 2) a response object of type id that in context sensitive. If the call is successful, the response object could be an NSArray, NSDictionary, or NSString depending on the request (see below). If the call is not successful, the response object will be an NSError.

login

PunchTab Sign-on

This method will go through the PunchTab sign-on process detailed above. If a user has already logged in (i.e. has a token), the login will succeed immediately.

    [myPTController login];
Single Sign-on (SSO)

This method will use your own user ID to authenticate the user. The user ID can be any string that you use to identify your users. The email address argument is optional.

    [myPtController loginWithUserId:@"user id" firstName:@"First name" lastName:@"last name" block:^(BOOL success, id response) {
        if (success) {
            [self setLoggedInState];
        }
    }];

Success Response Object

NSDictionary containing raw JSON user data

sendActivity: and sendActivity:withPoints:

This method will send one of the PunchTab activities to the server. The latter method lets you set a custom point value. Please see the PunchTab developer's site for more valid actions.

    [myPTController sendActivity:@"tweet" block:^(BOOL success, id response) {
        if (success) {
        }
];
    [myPTController sendActivity:@"comment" withPoints:200 block:^(BOOL success, id response) {
        if (success) {
        }
];
Success Response Object

NSDictionary containing the server response

getRewards

Gets the rewards available to the user. You can optionally set a limit on the number of rewards returned.

    [myPTController getRewards block:^(BOOL success, id response) {
        if (success) {
        }
];

    [myPTController getRewardsLimit:10 block:^(BOOL success, id response) {
        if (success) {
        }
];
Success Response Object

NSArray with list of rewards for the program

redeemReward:

Send the "redeem" activity for a given reward_id to the server. Redeeming a reward is an activity, so it returns a similar response

    [myPTController redeemReward:myRewardId block:^(BOOL success, id response) {
        if (success) {
        }
];

Success Response Object

NSDictionary containing the server response

getLeaderboard:

Gets the leaderboard for your rewards program. you can optionally get the current user's relative position data included.

    [myPTController getLeaderboard block:^(BOOL success, id response) {
        if (success) {
        }
];

    [myPTController getLeaderboardWithMe:YES block:^(BOOL success, id response) {
        if (success) {
        }
];

Success Response Object

NSArray with ordered list of users in leaderboard

There are more requests available and documented in PTController.h

Giveaway Support

PunchTab offers the ability to incentivize your users to download your mobile app by entering them in a PunchTab Giveaway when the app is started for the first time. You need not implement the rest of the loyalty platform nor do you need a valid Client ID for this functionality.

enterGiveaway: (class method)

In your appDelegate, just add the following to this method:

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        [PTController enterGiveaway];

        ...
    }

This will only attempt to enter the Giveaway one time.

Third party Package - License - Copyright / Creator

AFNetworking Copyright (c) 2011 Gowalla

Something went wrong with that request. Please try again.