Redirections and Actions

Once the scenario's project, application, products, and Thngs are set up in the EVRYTHNG Platform, the next step is to enable the scanning functionality that will enable you to gain insights from user behavior and in return offer the incentive that will be engaging users. For example, a promotional coupon code, video campaign, or social integrations.


## Creating Redirections

In order to provide a serialised scanning experience, each Thng that represents a single box of cereal must have its own unique QR code. In a real world application of this use-case, these individual QR codes will be printed on the individual boxes themselves, ready for use by consumers to scan the unique Thngs.

Creating a redirection (which includes the QR code URL) for any given Thng or product is a simple additional POST :shortDomain/redirections API request using the id of any existing Thng and a URL to some location the user will be redirected to.

An important feature is the use of {evrythngId} template in the defaultRedirectUrl (the destination to redirect the user to), which will be dynamically filled with the ID of the associated resource whenever the redirection is called. This allows the receiving website or web app to know straight away which resource was scanned, and so enables it to provide a more personalized/unique experience to the user.

Substitutions: :thngId, :shortDomain (tn.gg or etn.gg for the EU region)

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.io/v2/thngs/:thngId/redirector' \
  -d '{
    "defaultRedirectUrl": "https://www.supercrunchy.cereal?thng={thngId}"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "createdAt": 1522751950805,
  "updatedAt": 1522751950805,
  "defaultRedirectUrl": "https://www.supercruncy.cereal?thng=UnqdWBqkVXPwQpwaa2emyrAe",
  "evrythngUrl": "https://api.evrythng.com/thngs/UnqdWBqkVXPwQpwaa2emyrAe",
  "shortDomain": "tn.gg",
  "shortId": "NK1L5yWjQc",
  "hits": 0
}

Details of the redirection created are included in the response as the shortDomain and shortId fields. Note that the shortDomain may be different depending on the account region and setup. Thus the short URL (to be used by the user and 3rd party applications) for the Thng above will be as follows:

https://tn.gg/NK1L5yWjQc

The associated QR code representation of this redirection URL can be obtained and saved to disk as shown below:

Substitutions: :shortId

wget https://tn.gg/:shortId.png

The response is the QR code in PNG format that would be attached to the physical cereal box of Super Crunchy #34871.


Creating Actions and Action Types

With the data model describing the Thngs to be scanned by consumers set up, we can now turn our attention to the creating EVRYTHNG action resources that will allow us to track user behavior and app engagement.

Actions are the Platform resource model for events and notifications, and serve as a lasting record of discrete events that can occur in a variety of built-in and developer-defined types. They can also contain custom data fields that can be used to drive business logic or personalized experiences. In this example product scanning scenario, an action will be created in a variety of situations that will provide a history of successful engagements or failed scans for each individual Thng.

Each action created must have an action type type to describe its class. This is a similar relationship to that of Thngs as instances of products, but a key difference is that it is mandatory here.

📘

Note

There are also several built-in action types, which you can view by making a GET /actions request using the Operator API Key.

For this scenario, we will create new action types to represent the different types of event that could occur when the consumer is interacting with the product packaging via the QR code and some barcode scanning app.

By default, when an EVRYTHNG short URL is followed (i.e: a QR code is scanned, and the decoded short URL is opened in a web browser), an action is created of the implicitScans type, since a redirection implies a scan of the QR code in most cases. In addition to this functionality, we will add new custom action types to represent types of events more specific to this scenario.

When creating new action types, it is a requirement that the name starts with an underscore. The first action type we will create will be _ProductScanned which denotes that a known product was scanned by a consumer.

Substitutions: :projectId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.io/v2/actions?project=:projectId' \
  -d '{
    "name": "_ProductScanned"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UHqdGpydBgPw9pRwaE9XctCs",
  "createdAt": 1522768675251,
  "updatedAt": 1522768675251,
  "name": "_ProductScanned"
}

Now that the custom action type is in place, it can be used to create actions of that type. For any given box of cereal Thng, the first action in a consumer engagement context will likely be of this newly created _ProductScanned type. Creating one such action as a test is straightforward, and must include specifying the target thng in the payload:

Substitutions: :projectId, :thngId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.io/v2/actions/_ProductScanned?project=:projectId' \
  -d '{
    "type": "_ProductScanned",
    "thng": ":thngId"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UnqUGPkVeDswQKRaampwFa9e",
  "createdAt": 1522769540519,
  "timestamp": 1522769540519,
  "type": "_ProductScanned",
  "location": {
    "latitude": 51.45,
    "longitude": 0.15,
    "position": {
      "type": "Point",
      "coordinates": [
        0.15,
        51.45
      ]
    }
  },
  "locationSource": "geoIp",
  "context": {
    "city": "Dartford",
    "region": "England",
    "countryCode": "GB",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
    "timeZone": "Europe/London"
  },
  "createdByProject": "Unqde2GrBgPRtKaawhH9qr4d",
  "thng": "UnqdWBqkVXPwQpwaa2emyrAe",
  "product": "U4MUfRpBVDPRt5aaaFVC2dgp"
}

## More Action Types

In a real integration, the web app used by consumer would be responsible for creating actions of this type when the product is successfully scanned, as well as in some other possible situations that can be represented by the following additional example action types:

  • _ProductNotFound - The scan completed, but there was no known product found.
  • _ScanFailed - The scan failed to complete.
  • _RedirectionFollowed - The user followed the redirection to go on to the rest of the experience.

Actions with Locations

When an action is created, it will usually (if not always) contain some location data pertaining to the geographical context surrounding its creation. For example, with permission, an action can be created containing the user's location, which in turn can drive the decisions affecting which experience they get from the branded app using the Redirector feature.

Locations added to actions work in two ways:

  • The developer uses a device's GPS sensor to include precise location coordinates in the action creation request.
  • No coordinates are required, so the approximate location is added by the Platform using a GeoIP lookup using information about the request. This could point to a nearby exchange or data-center, for example.

When using the evrythng.js SDK, the geolocation setup option dictates whether the device's location will be attempted to be used. The default value is true, so it does not normally need to be specified:

// Turn on device location in actions (the default value)
evrythng.setup({ geolocation: true });

// Turn it off if required
evrythng.setup({ geolocation: false });

When creating a consumer engagement implementation, the best way to get the most data that can inform business decisions or drive the richest dynamic experiences is to create actions using the geolocation option left as true.


Using the Action Types

In the next section these new action types will be put to use in a simple scanning web application to allow tracking and aggregation of their various types of event. It is the strategic usage of different action types that enables the creation of insightful metrics and Dashboard widgets, which will also be covered later on.


What’s Next