passworks-ruby

Ruby bindings for the Passworks API (http://api.passworks.io)

Passworks Ruby API client can be installed via rubygems http://rubygems.org/gems/passworks.

Instalation

gem install passworks

Using bundler

gem 'passworks'

Basic usage

Configuring the client

The Passworks ruby client can be configured at class level or instance level.

# Class level configuration
Passworks.configure do |config|
  config.api_username = "your api username"
  config.api_secret   = "your api secret"
end

client = Passworks.new

# Instance level configuration
client = Passworks.new({
  api_username: 'your api username',
  api_secret: 'your api secret'
})

Examples

Certificates

Certificates are an essential part of every campaign.

They're used to uniquely identify a certain person or organization, and offer authenthicity reasurance. See Passworks API for mode information.

# Fetch and iterate through all your certificates
certificates = client.certificates.all
certificates.each do |certificate|
  puts certificate
end

# Fetch a specific certificate via uuid (uuid=c3d5fc64-3a43-4d3a-a167-473dfeb1edd3)
certificate = client.certificates.find('c3d5fc64-3a43-4d3a-a167-473dfeb1edd3')

Templates

A template is made up of several assets (icon being the only required one), and multiple customization options, such as colors.

You can find a template by it's ID:

# Fetch a specific template via uuid (uuid=c3d5fc64-3a43-4d3a-a167-473dfeb1edd3)
template = template.find('c3d5fc64-3a43-4d3a-a167-473dfeb1edd3')

# Delete template without deleting its associated assets
asset.delete(false)

# Delete template, and its associated assets
asset.delete(true)

Beware: in case you try to delete the assets, note that they will only be deleted, in case ALL of them were exclusive to this template, in which case ALL will be deleted. If just one of them was shared with some other template, none will be deleted.

Assets

Assets are the visual elements of the pass.

You can reuse assets, meaning that you can assign the same asset to multiple passes, reducing the number of asset operations and also reducing the amount of bandwidth required to create a pass. See Passworks API for mode information.

# Upload an asset (icon image)
asset_icon = client.assets.create({ file: '/path-to-file/icon-file.png', asset_type: 'icon' })

# Fetch and iterate through all your assets
assets = client.assets.all
assets.each do |asset|
  puts asset
end

# Fetch a specific assets via uuid (uuid=c3d5fc64-3a43-4d3a-a167-473dfeb1edd3)
asset = client.assets.find('c3d5fc64-3a43-4d3a-a167-473dfeb1edd3')

# Delete asset without loading it first
client.assets.delete('c3d5fc64-3a43-4d3a-a167-473dfeb1edd3')

# delete the asset instance (loading first the asset)
asset.delete

Coupons

Coupons can be used to offer customers a discount or promotion, or as a general proximity marketing asset. See Passworks API for mode information.

# Create a coupon campaign
coupon_campaign = client.coupons.create({
  name: "my first coupon campaign",
  icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3"
})

# Add a pass the the coupon campaign
# see [Coupon API documentation for details about the valid coupon fields
# https://github.com/passworks/passworks-api/blob/master/sections/coupon.md
coupon_pass = coupon_campaign.passes.create({
  primary_fields: [
    {
      key: "key1",
      label: "label1",
      value: "value1"
    }
  ]
})

# Fetch and print all passes from the `coupon_campaign` campaign
coupon_campaign.passes.all.each do |coupon_pass|
  puts coupon_pass
end

# send push notification all users of a coupon campaign
coupon_campaign.push

# Send push notification to the users of a given passe of the `coupon_campaign`
coupon_campaign.passes.all.first.push

# Update coupon pass
# the `update` method returns the updated PassResource instance
coupon_pass         = coupon_campaign.passes.all.first
updated_coupon_pass = coupon_pass.update({
  primary_fields: [
    {
      key: "key2",
      label: "label2",
      value: "value2"
    }
  ]
})

Store Cards

The Passworks API can be used to create loyalty or event tier programs to reward your customers for using your services. See Passworks API for mode information.

# Create a store card campaign
coupon_campaign = client.store_cards.create({
  name: "my first store card campaign",
  icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3"
})

# Add a pass the the store card campaign
# see [Store Card API documentation for details about the valid store card fields
# https://github.com/passworks/passworks-api/blob/master/sections/store_card.md
store_card_pass = store_card_campaign.passes.create({
  primary_fields: [
    {
      key: "key1",
      label: "label1",
      value: "value1"
    }
  ]
})

# Fetch and print all passes from the `store_card_campaign` campaign
store_card_campaign.passes.all.each do |store_card_pass|
  puts store_card_pass
end

# send push notification all users of a store card campaign
store_card_campaign.push

# Send push notification to the users of a given passe of the `store_card_campaign`
store_card_campaign.passes.all.first.push

# Update store card pass
# the `update` method returns the updated PassResource instance
store_card_pass     = store_card_campaign.passes.all.first
updated_coupon_pass = store_card_pass.update({
  primary_fields: [
    {
      key: "key2",
      label: "label2",
      value: "value2"
    }
  ]
})

Event Tickets

Event Tickets are passes used for events such as concerts, movie tickets, galas, meetings or other types of activity that happen in a specific time or day. See Passworks API for mode information.

# Create a event ticket campaign
event_ticket_campaign = client.event_tickets.create({
  name: "my first event ticket campaign",
  icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3"
})

# Add a pass the the event ticket campaign
# see [Event Ticket API documentation for details about the valid event ticket fields
# https://github.com/passworks/passworks-api/blob/master/sections/event_ticket.md
event_ticket_campaign = event_ticket_campaign.passes.create({
  primary_fields: [
    {
      key: "key1",
      label: "label1",
      value: "value1"
    }
  ]
})

# Fetch and print all passes from the `event_ticket_campaign` campaign
event_ticket_campaign.passes.all.each do |event_ticket_pass|
  puts event_ticket_pass
end

# send push notification all users of a store card campaign
event_ticket_campaign.push

# Send push notification to the users of a given passe of the `event_ticket_campaign`
event_ticket_campaign.passes.all.first.push

# Update event ticket pass
# the `update` method returns the updated PassResource instance
event_ticket_pass         = event_ticket_campaign.passes.all.first
updated_event_ticket_pass = event_ticket_pass.update({
  primary_fields: [
    {
      key: "key2",
      label: "label2",
      value: "value2"
    }
  ]
})

Bording Passes

Boarding passes can be airplane, bus, train, or boat tickets. You also can create generic boarding passes. See Passworks API for mode information.

# Create a boarding pass campaign
boarding_pass_campaign = client.boarding_passes.create({
  name: "my first boarding pass campaign",
  icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3",
  transit_type: "air"
})

# Add a pass the the boarding pass campaign
# see [Boarding Pass API documentation for details about the valid boarding passe fields
# https://github.com/passworks/passworks-api/blob/master/sections/boarding_pass.md
boarding_pass_pass = boarding_pass_campaign.passes.create({
  primary_fields: [
    {
      key: "key1",
      label: "label1",
      value: "value1"
    }
  ]
})

# Fetch and print all passes from the `boarding_pass_campaign` campaign
boarding_pass_campaign.passes.all.each do |boarding_pass|
  puts boarding_pass
end

# send push notification all users of a boarding pass campaign
boarding_pass_campaign.push

# Send push notification to the users of a given passe of the `boarding_pass_campaign`
boarding_pass_campaign.passes.all.first.push

# Update event ticket pass
# the `update` method returns the updated PassResource instance
boarding_pass_pass         = boarding_pass_campaign.passes.all.first
updated_boarding_pass_pass = boarding_pass_pass.update({
  primary_fields: [
    {
      key: "key2",
      label: "label2",
      value: "value2"
    }
  ]
})

Generic

Generic passes can be used for anything that doesn't fit in the other pass categories. See Passworks API for mode information.

# Create a generic pass campaign
generic_campaign = client.boarding_passes.create({
  name: "my first generic campaign",
  icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3"
})

# Add a pass the the generic campaign
# see [Generic Pass API documentation for details about the valid generic passe fields
# https://github.com/passworks/passworks-api/blob/master/sections/generic.md
generic_pass = generic_campaign.passes.create({
  primary_fields: [
    {
      key: "key1",
      label: "label1",
      value: "value1"
    }
  ]
})

# Fetch and print all passes from the `generic_campaign` campaign
generic_campaign.passes.all.each do |generic_pass|
  puts generic_pass
end

# send push notification all users of an generic pass campaign
generic_campaign.push

# Send push notification to the users of a given passe of the `generic_campaign`
generic_campaign.passes.all.first.push

# Update event ticket pass
# the `update` method returns the updated PassResource instance
generic_pass         = generic_campaign.passes.all.first
updated_generic_pass = generic_pass.update({
  primary_fields: [
    {
      key: "key2",
      label: "label2",
      value: "value2"
    }
  ]
})

Updating campaign passes in a single request

It's possible to update the passes presentation fields (primary_fields, secondary_fields, auxiliary_fields and back_fields) using the Campaign data in a single request.

For that you only need to follow the 2 steps:

Update the campaign with the intended information.
Call the merge method in the campaign, this method merges the presentation fields of the campaign with the passes information.

	# Find the campaign that you wish to update
	campaign = client.coupons.find("c3d5fc64-3a43-4d3a-a167-473dfeb1edd3")

	# Update the campaign
	campaign.update({
		secondary_fields: [
			{
				key: "date",
				label: "Promotion expires at",
				value: "31/12/2015"
			}
		]
	})

	# Update the campaign passes
	campaign.merge

IMPORTANTE: This method updates all passes beacons and locations (geo locations) with the Campaign defined ones, overriding the existing in the passes.

Understanding behaviour fields (fixed vs dynamic content)

The presentation fields (primary_fields, secondary_fields, auxiliary_fields and back_fields) have a new (behaviour) attribute. This attribute can have one of two values: fixed or dynamic (by default the behaviour is set to fixed).

fixed

fixed means that the value is static: every pass will have the same label and value for this field. So when you call the merge method in the Ruby client this field will be added or overriden (if the field with the same key exists) in every pass even if you had previously customized the value per pass. Don't use the type of field for custom fields in your passes eg: name, client id, ticket number ,etc. This type of behaviour is a good fit for fields that are the same across all passes eg: event date, event location, flight number, etc.
dynamic

The dynamic behaviour defines the field as a custom updated field that shouldn't be updated on a bulk update when the merge method is called. This field will only be updated when the user updates that field specifically for that pass. This type of behaviour is a good fit for custom fields like ticket number, user name, boarding number, seat number, etc..

Reports

The API provides two kinds of reports regarding the campaigns, a detailed day by day report or a totalization of passes issued.

The endpoints are the same for any kind of campaign (coupons, event tickets, boarding passes, etc) and are very easy to use:

# Find the campaign that you wish get the report
# Remember that it can be used for any kind of campaign

campaign = client.coupons.find("c3d5fc64-3a43-4d3a-a167-473dfeb1edd3")

# The period is optional, when not provided, a month before the current
# date is going to be assumed.

report_period = {
   start_date: '2010-10-10',
   end_date: '2016-06-30
}
daily_report = campaign.daily_report(report_period)

# You can also find a totalization (no arguments received)
total_report = campaign.total_report

Output

Daily

daily_report = campaign.daily_report(report_period)
{
  "campaign_id" => "54612b54-71b8-490e-a5a8-600fc497227d",
  "start_date" => "2016-06-01T14:51:15.248 Z",
  "end_date" => "2016-07-01",
  "report" => {
    "2016-06-30" => {
      "installs_count" => 0,
      "uninstalls_count" => 0,
      "redeems_count" => 0,
      "fetches_count" => 0,
      "downloads_count" => 1,
      "views_count" => 0,
      "creates_count" => 1,
      "expires_count" => 0,
      "pushes_count" => 0,
      "updates_count" => 0,
      "webhooks_count" => 0,
      "api_calls_count" => 0,
      "distribution_updates_count" => 0,
      "i" => {
        "ios" => 0,
        "android" => 0,
        "wp" => 0
      },
      "u" => {
        "ios" => 0,
        "android" => 0,
        "wp" => 0
      },
      "active_count" => 0,
      "removed_count" => 0
    }
  }
}

Totals

total_report = campaign.total_report
{
  "campaign_id" => "54612b54-71b8-490e-a5a8-600fc497227d",
  "report" => {
    "apple" => { "installs_count" => 0, "uninstalls_count" => 0 },
    "android" => { "installs_count" => 0, "uninstalls_count" => 0 }
    "installs_count" => 0,
    "uninstalls_count" => 0,
    "redeems_count" => 0,
    "fetches_count" => 0,
    "downloads_count" => 2,
    "views_count" => 0,
    "creates_count" => 2,
    "expires_count" => 0,
    "pushes_count" => 0,
    "updates_count" => 0,
    "webhooks_count" => 0,
    "api_calls_count" => 0,
    "distribution_updates_count" => 0,
    "active_count" => 0,
    "removed_count" => 0
  }
}

Documentation

For more information about the API please please refere to https://github.com/passworks/passworks-api

For more examples about the Ruby client try browsing the wiki

Help us make it better

Please tell us how we can make the Ruby client better. If you have a specific feature request or if you found a bug, please use GitHub issues. Fork these docs and send a pull request with improvements.

To talk with us and other developers about the API open a support ticket or mail us at api at passworks.io if you need to talk to us.

passworks

Development

Runtime