Permalink
Browse files

remote_form_url support

  • Loading branch information...
lmmendes committed Oct 5, 2017
1 parent 03552c2 commit 51cd029462f9b976e1b09617cdc7ae6fef847d3f
Showing with 283 additions and 0 deletions.
  1. +283 −0 v2/sections/advanced-features.md
@@ -1,2 +1,285 @@
Advanced Features
===============
## Setting up a campaign with a remote\_form\_url
When creating a campaign using one of the existing endpoints, eg: `coupons`, `event_tickets`, `generics` just append the `remote_form_url` parameter to your already existing campaign fields.
See the following example where we will be adding `remote_form_url` attribute with the value **http://example.org**.
### Example
```
POST http://api.passworks.io/v2/coupons/
```
Payload:
```
{
"coupon": {
"name": "Remote Form URL Example",
"template_id": "af61b02d-a89d-4159-8f76-a39c07e5ad4c",
"remote_form_url": "http://example.org"
}
}
```
Response:
```
{
"id": "695b0903-5cb6-4a19-b835-f5d074347f5c",
"name": "Remote Form URL Example",
"template_id": "af61b02d-a89d-4159-8f76-a39c07e5ad4c",
"organization_name": "Luis",
"barcode": {
"format": "none",
"message": "",
"alt_text": "",
"alt_text_type": "mirror"
},
"render_on_short_url": false,
"remote_form_url": "http://example.org",
"created_at": "2016-08-29T14:07:08Z",
"updated_at": "2016-08-29T14:07:08Z",
"distributions": [
{
"id": "3803869e-9302-4197-a57f-9cb1d3cd405c",
"distribution_type": "downloadPage",
"state": "published",
"page_url": "https://passworks.io/p/PlOKQOhqCg",
"pkpass_url": "https://passworks.io/p/PlOKQOhqCg.pkpass",
"preview_url": "https://passworks.io/p/PlOKQOhqCg.png",
"page_short_url": "https://pass.yt:3000/d/Xr",
"pkpass_short_url": "http://passs.ly:3000/d/Xr.pkpass",
"preview_short_url": "http://passs.ly:3000/d/Xr.png",
"created_at": "2016-08-29T14:07:08.888Z",
"updated_at": "2016-08-29T14:07:09.010Z",
"published_at": "2016-08-29T14:07:09.015Z"
}
]
}
```
In the response you can see a `remote_form_url` attribute with the value **http://example.org** as expected.
When redirecting Passworks platform will append a query parameter called campaign_id to the end of the URL turning **http://example.org** in to **http://example.org?campaign_id=<campaign_id>**
So in this case when the user is redirected to the `remote_form_url` the url used will be **http://example.org?campaign_id=695b0903-5cb6-4a19-b835-f5d074347f5c** (NOTE: The redirect is always a GET request).
## Fetching the campaign fields
You can grab the campaign fields calling the `fields` method of the `remote_forms` endpoint and passing as a argument the `campaign_id`.
The `campaign_id` is the ID of a any kind of campaign, eg: `coupon`, `event_ticket`, `boarding_pass`, etc..
```
GET http://api.passworks.io/v2/remote_forms/<campaign_id>/fields
```
The response will always be a hash containing 3 top level keys: `fields`, `dynamic_fields_keys`, `static_fields_keys`
| Key name | Type | Description |
|----------|------|-------------|
| fields | Hash | Hash of all available campaign fields, static or dynamic, the key of each field is also the key of the hash |
| dynamic\_fields\_keys | Array | The keys of all the dynamic fields |
| static\_fields\_keys | Array | The keys of all static fields |
### Example
Requesting the fields of the campaign `f1eb7fba-392b-489c-a0dd-8bf8892ce349` :
```
http://api.passworks.io/v2/remote_forms/f1eb7fba-392b-489c-a0dd-8bf8892ce349/fields
```
The response
```
{
"fields": {
"name": {
"key": "name",
"label": "Name",
"value": "name",
"behaviour": "dynamic"
},
"age": {
"key": "age",
"label": "Age",
"value": "",
"behaviour": "dynamic"
},
"location": {
"key": "location",
"label": "Location",
"value": "Av da Liberdade",
"behaviour": "fixed"
}
},
"dynamic_fields_keys": [
"name",
"age"
],
"static_fields_keys": [
"location"
]
}
```
## Posting the form
Creating a new pass by submiting the dynamic fields is easy, just call the `submit` method of the `remote_forms` endpoint with the `dynamic fields` in the body.
```
POST http://api.passworks.io/v2/remote_forms/<campaign_id>/submit
```
## Example
Let's submit the `age` and `name` values using our endpoint, let's assume that the campaign_id is `f1eb7fba-392b-489c-a0dd-8bf8892ce349`
> NOTE: If you supply a `beacons` and/or `locations` array of hashes the beacons and locations will be merged with the pass (overriding any default `beacons` or `locations` already defined in the campaign).
```
POST http://api.passworks.io/v2/remote_forms/f1eb7fba-392b-489c-a0dd-8bf8892ce349/submit
```
With the following payload:
```
{
"name": "Kermit the Frog",
"age": "61",
"beacons": [
{
"proximity_uuid": "ec961b5b-9a63-4eb5-9463-c19bd5aca7ba",
"major": 1,
"minor": 1,
"relevant_text": "Elmo"
},
{
"proximity_uuid": "ec961b5b-9a63-4eb5-9463-c19bd5aca7ba",
"major": 2,
"minor": 2,
"relevant_text": "Big Bird"
}
],
"locations": [
{
"latitude": "38.707739",
"longitude": "-9.147581",
"relevant_text": "Grover"
}
]
}
```
Calling the above endpoint will result in the following answer: (just redirect the user to `page_short_url` from the response).
```
{
"id": "175d218e-88fb-4af1-afb8-86512dccf9fb",
"campaign_id": "f1eb7fba-392b-489c-a0dd-8bf8892ce349",
"voided": false,
"serial_number": "b3cafaa7-e180-42e0-813f-3025a5be56f2",
"redeem_code": "00000027",
"redeemed_count": 0,
"barcode": {
"format": "none",
"message": "",
"alt_text": "",
"alt_text_type": "mirror"
},
"barcodes": [
{
"format": "none",
"message": "",
"alt_text": "",
"alt_text_type": "mirror"
}
],
"expiration_date": "2016-08-09T14:30:54.000+00:00",
"max_distance": 30,
"relevant_date": null,
"header_fields": [],
"primary_fields": [],
"secondary_fields": [
{
"key": "name",
"value": "Kermit the Frog",
"label": "Name",
"behaviour": "dynamic"
},
{
"key": "age",
"value": "61",
"label": "Age",
"behaviour": "dynamic"
}
],
"auxiliary_fields": [],
"back_fields": [
{
"key": "location",
"value": "Av da Liberdade",
"label": "Location",
"behaviour": "fixed"
}
],
"locations": [
{
"name": null,
"altitude": null,
"latitude": 38.707739,
"longitude": -9.147581,
"relevant_text": "Grover"
}
],
"beacons": [
{
"major": 1,
"minor": 1,
"proximity_uuid": "ec961b5b-9a63-4eb5-9463-c19bd5aca7ba",
"relevant_text": "Elmo"
},
{
"major": 2,
"minor": 2,
"proximity_uuid": "ec961b5b-9a63-4eb5-9463-c19bd5aca7ba",
"relevant_text": "Big Bird"
}
],
"page_url": "https://passworks.io/p/ZpCCm1MEGA/ff2oP4iHmEQ2p60rQxxWlw",
"pkpass_url": "https://passworks.io/p/ZpCCm1MEGA/ff2oP4iHmEQ2p60rQxxWlw.pkpass",
"page_short_url": "http://pass.ly/p/Wr",
"pkpass_short_url": "http://pass.ly/p/Wr.pkpass",
"created_at": "2016-08-29T15:25:15Z",
"updated_at": "2016-08-29T15:25:16Z"
}
```
## Custom barcode
If you wish to specify a custom barcode, make sure that your campaign's "code_type" attribute is set to `per_pass` and when submiting the form just submit the `barcodes` array with the barcode formats that you wish to support, eg:
```
{
"barcodes": [
{
format: "qrcode",
message: "123456"
},
{
format: "aztec",
message: "123456"
}
]
}
```
Use the same message content for all types of barcodes that you support.

0 comments on commit 51cd029

Please sign in to comment.