Redirections and Actions

After 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 lets you gain insights from user behavior and, in return, offer the incentive that engages users. For example, a promotional coupon code, video campaign, or social integrations.

Creating Redirections

To provide a serialized 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 are 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 a Thng or product requires a simple additional POST :shortDomain/redirections API request using the id of an existing Thng and a URL to the 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 is dynamically filled with the ID of the associated resource when the redirection is called. This immediately tells the receiving website or web app which resource was scanned and 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 new redirection 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 in the example above is:

https://tn.gg/NK1L5yWjQc

You can get the associated QR code representation of this redirection URL using cURL as shown below:

Substitutions: :shortId

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

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

Creating Actions and Action Types

With the data model set up, describing the Thngs to be scanned by consumers, let's turn our attention to the creating EVRYTHNG action resources that allows us to track user behavior and app engagement.

Actions are the Platform resource models for events and notifications. They 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 drive business logic or personalized experiences. In this example product scanning scenario, an action is created in a variety of situations that provide a history of successful engagements or failed scans for each 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 action types to represent the different types of events that could occur when the consumer is interacting with the product packaging through the QR code and a barcode scanning app.

By default, when an EVRYTHNG short URL is followed (that is, a QR code is scanned and the decoded short URL is opened in a web browser), an action is created of the implicitScans type, because a redirection implies a scan of the QR code in most cases. We will also add custom action types to represent types of events more specific to this scenario.

When you create action types, the name must start with an underscore. The first action type we will create is _ProductScanned, which indicates 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 create actions of that type. For any Thng, the first action in a consumer engagement context is likely 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 usually (if not always) contains some location data pertaining to the geographical context surrounding its creation. For example, with the device owner's 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 Platform adds the approximate location by 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 is used (with the device owner's permission). The default value is true, so it doesn't 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 set to true.

Using the Action Types

In the next section, these new action types will be used in a simple scanning web application to allow tracking and aggregation of their various types of events. The strategic use of different action types enables the creation of insightful metrics and Dashboard widgets, which are covered later on.