Skip to content

Nov 13 / Rupak Ganguly

Ruby wrapper for PunchTab API

A while back, in May 2013, I had worked on writing a Ruby wrapper for the PunchTab API. I found the concept of PunchTab‘s loyalty program interesting, and wanted to integrate that into my web apps. So, I wrote the wrapper. See the code snippets below, to see how to use the wrapper to access PunchTab’s loyalty programs.

Getting Started

Installation

gem install punchtab

Authenticate using Single Sign On (SSO)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# authenticate with PunchTab
client = Punchtab::Client.new(
  :client_id  => 'your client_id',
  :access_key => 'your access_key',
  :secret_key => 'your secret_key',
  :domain     => 'www.mydomain.com',
  :user_info => {
    :first_name => 'your first_name',
    :last_name  => 'your last_name',
    :email      => 'me@mydomain.com'}
)
# if authentication is successful, you should get an access token back
puts "Access Token: #{client.access_token}"
 
# if authentication fails, an exception is thrown

Note: You can get all of the above values from your Punchtab developer account page.

Authentication

1
2
3
4
5
6
7
# check authentication status
client.status
=> {"status"=>"connected",
    "authResponse"=>
    {"userID"=>"111111_1111",
     "uid"=>"111111",
     "accessToken"=>"ed17a5f0ad9e52db0576f39602083dc7"}}
1
2
3
# logout
client.logout
=> {"status"=>"disconnected"}

Activity

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# get all activities
client.get_activity
=> [{"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"comment",
  "referrer"=>"http://www.webintellix.com",
  "points"=>600,
  "date_created"=>"2013-05-23 06:37:54",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222},
 {"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"comment",
  "referrer"=>"http://www.webintellix.com",
  "points"=>600,
  "date_created"=>"2013-05-22 04:50:53",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222},
 {"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"plusone",
  "referrer"=>"http://www.webintellix.com",
  "points"=>500,
  "date_created"=>"2013-05-22 03:36:13",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222},
 {"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"like",
  "referrer"=>"http://www.webintellix.com",
  "points"=>400,
  "date_created"=>"2013-05-22 02:58:27",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222}]
 
# get 2 activities
client.get_activity(:limit => 2)
=> [{"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"comment",
  "referrer"=>"http://www.webintellix.com",
  "points"=>600,
  "date_created"=>"2013-05-22 04:50:53",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222},
 {"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"plusone",
  "referrer"=>"http://www.webintellix.com",
  "points"=>500,
  "date_created"=>"2013-05-22 03:36:13",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222}]
1
2
3
4
5
6
7
8
9
10
# get only 'like' activities
client.get_activity(:activity_name => :like)
=> [{"domain"=>"www.webintellix.com",
  "display_name"=>"Webintellix",
  "name"=>"like",
  "referrer"=>"http://www.webintellix.com",
  "points"=>400,
  "date_created"=>"2013-05-22 02:58:27",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222}]
1
2
3
4
5
6
7
8
9
10
11
# create a new activity, and assign it relevant 'points'
client.create_activity(:comment, 600)
=> [{"domain"=>"www.webintellix.com",
  "user_id"=>111111,
  "name"=>"comment",
  "referrer"=>"http://www.webintellix.com",
  "points"=>600,
  "date_created"=>"2013-05-22 03:54:42",
  "_id"=>"xxxxxxxxxxxxxxxxxx",
  "publisher_id"=>2222,
  "display_name"=>"Webintellix"}]
1
2
# redeem offer for an activity using a 'reward_id'
client.redeem_activity_offer(123)

User

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# get details about the current user
client.get_user
=> {"first_name"=>"Rupak",
 "last_name"=>"Ganguly",
 "user_id"=>111111,
 "name"=>"Rupak Ganguly",
 "timeline"=>false,
 "badge_count"=>0,
 "foursquare"=>false,
 "optedOut"=>false,
 "redemptions"=>0,
 "new_lb"=>1,
 "redeemable_points"=>3200,
 "total_points_earned"=>3200,
 "avatar"=>
  "https://s3.amazonaws.com/punchtab-static/img/default_facebook_avatar.jpg"}

Reward

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# get all the rewards
client.get_reward
=> [{"merchantname"=>"Target",
  "image"=>{},
  "label"=>"$5 Target Gift Card",
  "points"=>15000,
  "redeemable"=>false,
  "shipping_address"=>false,
  "id"=>33333,
  "reward_id"=>33333},
 {"merchantname"=>"Starbucks",
  "image"=>{},
  "label"=>"$5 Starbucks Card",
  "points"=>10000,
  "redeemable"=>false,
  "shipping_address"=>false,
  "id"=>44444,
  "reward_id"=>44444}]
 
# get specified number of rewards
client.get_reward(:limit => 1)
=> [{"merchantname"=>"Target",
  "image"=>{},
  "label"=>"$5 Target Gift Card",
  "points"=>15000,
  "redeemable"=>false,
  "shipping_address"=>false,
  "id"=>33333,
  "reward_id"=>33333}]

Leaderboard

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# get the current user's leaderboard
client.get_leaderboard
=> [{"username"=>"111111_1111",
  "recent_activity"=>
   {"domain"=>"www.webintellix.com",
    "display_name"=>"Webintellix",
    "name"=>"comment",
    "referrer"=>"",
    "points"=>600,
    "date_created"=>"2013-05-23 06:37:54.296496",
    "_id"=>"",
    "publisher_id"=>2222},
  "name"=>"Rupak Ganguly",
  "self"=>true,
  "rank"=>1,
  "points"=>3200,
  "avatar"=>
   "https://s3.amazonaws.com/punchtab-static/img/default_facebook_avatar.jpg",
  "user_id"=>111111}]
 
# get the specified user's leaderboard
client.get_leaderboard(111111)
=> [{"username"=>"111111_1111",
  "recent_activity"=>
   {"domain"=>"www.webintellix.com",
    "display_name"=>"Webintellix",
    "name"=>"comment",
    "referrer"=>"",
    "points"=>600,
    "date_created"=>"2013-05-23 06:37:54.296496",
    "_id"=>"",
    "publisher_id"=>2222},
  "name"=>"Rupak Ganguly",
  "self"=>true,
  "rank"=>1,
  "points"=>3200,
  "avatar"=>
   "https://s3.amazonaws.com/punchtab-static/img/default_facebook_avatar.jpg",
  "user_id"=>111111}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# get leaderboard for current user with optional parameters
client.get_leaderboard(:days => 10, :limit => 3, :page => 1)
=> [{"username"=>"111111_1111",
  "user_id"=>111111,
  "name"=>"Rupak Ganguly",
  "self"=>true,
  "rank"=>1,
  "points"=>3200,
  "avatar"=>
   "https://s3.amazonaws.com/punchtab-static/img/default_facebook_avatar.jpg",
  "recent_activity"=>
   {"domain"=>"www.webintellix.com",
    "display_name"=>"Webintellix",
    "name"=>"comment",
    "referrer"=>"http://www.webintellix.com",
    "points"=>600,
    "date_created"=>"2013-05-23 06:37:54",
    "_id"=>"xxxxxxxxxxxxxxxxxxx",
    "publisher_id"=>2222}}]
 
# get leaderboard for specified user's leaderboard, with optional parameters
client.get_leaderboard(:with => 111111, :days => 10, :limit => 3, :page => 1)
=> [{"username"=>"111111_1111",
  "user_id"=>111111,
  "name"=>"Rupak Ganguly",
  "self"=>true,
  "rank"=>1,
  "points"=>3200,
  "avatar"=>
   "https://s3.amazonaws.com/punchtab-static/img/default_facebook_avatar.jpg",
  "recent_activity"=>
   {"domain"=>"www.webintellix.com",
    "display_name"=>"Webintellix",
    "name"=>"comment",
    "referrer"=>"http://www.webintellix.com",
    "points"=>600,
    "date_created"=>"2013-05-23 06:37:54",
    "_id"=>"xxxxxxxxxxxxxxxxxxx",
    "publisher_id"=>2222}}]

So, you can take a look at the source code or download the PunchTab gem. Hope this gem will make its way into your application. If you have any feedback or comments, please do express your thoughts.

Leave a Comment