README.md in passworks-2.0.2 vs README.md in passworks-2.0.3

- old
+ new

@@ -38,19 +38,23 @@ ``` ```ruby # Instance level configuration client = Passworks.new({ - api_username: 'your api username', - api_secret: 'your api secret' + 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](https://github.com/passworks/passworks-api/blob/master/v2/sections/certificates.md#certificates) for mode information. + ```ruby # Fetch and iterate through all your certificates certificates = client.certificates.all certificates.each do |certificate| puts certificate @@ -60,10 +64,14 @@ certificate = client.certificates.find('c3d5fc64-3a43-4d3a-a167-473dfeb1edd3') ``` ### 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](https://github.com/passworks/passworks-api/blob/master/v2/sections/assets.md#assets) for mode information. + ```ruby # 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 @@ -82,10 +90,12 @@ asset.delete ``` ### Coupons +Coupons can be used to offer customers a discount or promotion, or as a general proximity marketing asset. [See Passworks API](https://github.com/passworks/passworks-api/blob/master/v2/sections/coupon.md) for mode information. + ```ruby # Create a coupon campaign coupon_campaign = client.coupons.create({ name: "my first coupon campaign", icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3" @@ -129,10 +139,13 @@ }) ``` ### 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](https://github.com/passworks/passworks-api/blob/master/v2/sections/store_card.md) for mode information. + + ```ruby # Create a store card campaign coupon_campaign = client.store_cards.create({ name: "my first store card campaign", icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3" @@ -176,10 +189,12 @@ }) ``` ### 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](https://github.com/passworks/passworks-api/blob/master/v2/sections/event_ticket.md) for mode information. + ```ruby # 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" @@ -223,10 +238,13 @@ }) ``` ### Bording Passes +Boarding passes can be airplane, bus, train, or boat tickets. You also can create generic boarding passes. [See Passworks API](https://github.com/passworks/passworks-api/blob/master/v2/sections/boarding_pass.md) for mode information. + + ```ruby # 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", @@ -271,10 +289,12 @@ }) ``` ### Generic +Generic passes can be used for anything that doesn't fit in the other pass categories. [See Passworks API](https://github.com/passworks/passworks-api/blob/master/v2/sections/generic.md) for mode information. + ```ruby # Create a generic pass campaign generic_campaign = client.boarding_passes.create({ name: "my first generic campaign", icon_id: "c3d5fc64-3a43-4d3a-a167-473dfeb1edd3" @@ -315,9 +335,56 @@ 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: + +1. Update the campaign with the intended information. +2. Call the `merge` method in the campaign, this method merges the presentation fields of the campaign with the passes information. + +```ruby + # 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.. + ## Documentation For more information about the API please please refere to [https://github.com/passworks/passworks-api](https://github.com/passworks/passworks-api)