Developer Hub

Welcome to the EVRYTHNG Developer Hub! Here you will find all the information you need to create your EVRYTHNG apps and integrations. We have conceptual guides, walkthroughs, and tutorials as well as a complete API reference.

Featured Pages

Real-time Web Product Scanning

One of the most common ways to integrate the EVRYTHNG Platform into a consumer product’s life cycle is to enable consumers to engage with the product (and therefore also the brand that produced it) through some kind of on-pack trigger. Common examples include QR codes, DataMatrix codes, or the common GS1 UPC/EAN barcodes, which can be spotted on most products available in shops and supermarkets.

This kind of integration offers big benefits to both the brand and the individual consumer including insight into product origin, rewards, special offers, engagement metrics, and more, all made possible through the trigger’s ability to connect to the product’s online digital identity. A common approach to building this integration involves a brand-centric mobile experience delivered through a web-based application, such as a campaign page or longer-lived part of the brand website. Examples of this kind of engagement mechanism include a ‘scan to win!’ or ‘register to earn rewards’ scenario.

Such an example application is shown below. It typically involves branding, a call to action, and a view into the camera viewfinder so that the user can aim the camera effectively:

Traditionally this sort of application is built with one of our web SDKs - scanthng.js, which allows developers to augment their web apps with the ability to scan one of around 20 different kinds of barcode directly from a mobile web browser, and find out which EVRYTHNG product or Thng it is associated to. This can then power an experience with details about that product (for provenance, authenticity, or informative purposes) or perform a static or dynamic redirection to some other brand page or resource. The benefit of using our SDK for this purpose is twofold:

No need to write code for scanning, uploading, matching products from scratch.
Automatic querying and discovery of the full product data the barcode refers to.

This walkthrough will show you how easy it is to create just such a scanning experience that will allow a deep level of engagement between a consumer and the brand.


Setting up the account

To get started, log into or create an EVRYTHNG account using the Dashboard. This will be where all the data items are set up that power the redirection experience.

Once you are logged into the account, choose or create a project. Projects are used to group resources according to their purpose. An example project is shown below:

Next, create an application within this project. Application resources represent external apps, including the web app that this walkthrough will help you create, by providing context and credentials (specifically API keys). You can do this using the ‘Applications’ section of the left-hand navigation, making sure the correct project is selected at the top. An example is shown below:

Once the application has been created, you will be able to copy the Application API Key that will be used to authenticate the web scanning app. Do this by clicking ‘Show key’ under ‘API Key’ and using the copy button to securely copy the entire key. Paste the key somewhere local so that you can copy and paste other things until you are ready to use it.


Setting up the product

The web app you will create later on in this walkthrough will be used to scan a QR code located on a physical product. For testing purposes, you will create a product resources in the EVRYTHNG platform to represent the physical item and to collect action data on it. In the case of scanning the QR code, actions will be created each time it is scanned by a consumer, and are also an opportunity to add a dynamic redirection depending on context items such as location, demographics, time, etc. using Redirector.

Create a new product resource using the ‘Products’ section of the left-hand navigation, making sure that the correct project is selected at the top. This ensures that the Application API Key will be able to see the product by sharing the same project scope. An example product is shown below:

Note that this example includes the gs1:01 (GTIN) value in its identifiers - this will allow you to use the GS1 Digital Link standard, and refer to the product using a URL that is readable by phones as well as a point-of-sale system.

The final part of the product set up is its redirection. In the EVRYTHNG Platform, products and Thngs can be associated with a redirection to a static URL such as a product information or campaign page. In addition to this, the redirection can also be dynamic as previously mentioned using Redirector.

You can set up the redirection for this new product using the ‘Setup redirection’ button on the right hand side of the product’s details page in the Dashboard. An example redirection setup is shown below, and describes the short URL shown to consumers (either as a link or a QR code) and where the user will eventually be redirected to.

Once the redirection is set up, you can test it out by scanning the QR code shown in the product’s details page with any available mobile barcode scanner app (or some built-in feature such as Google Lens or the iOS Camera application). If you includes any of the available GS1 Digital Link identifiers, both the short URL QR code and a GS1 Digital Link QR code will be shown for you to scan. Do this scan now to confirm the redirection is working.

For added realism, add the product’s QR code to the example template bottle label below and wrap it around a drinks bottle of choice to better emulate scanning the physical product for a consumer experience.


Setting up a scanning web app

With the account setup complete, it is time to create a simple scanning web application that can be customised by the brand as required, and uses the scanthng.js SDK to easily scan the barcode attached to the product and identify the full product in the EVRYTHNG Platform. In this walkthrough we will explain the general steps, and then present a simple finished implementation to use as an example.

The web app being developed will need to include the following dependencies, either as <script> tags or local files:

  • evrythng.js - the EVRYTHNG JavaScript SDK that allows easy access to the resources in the account.

  • scanthng.js - a plugin for evrythng.js that adds the ability to scan barcodes and identify the products and Thngs that they are associated with.

  • jsQR - dependency for scanthng.js that allows decoding of QR codes within the browser, removing the need for an external service.

The first step required when building a web app with evrythng.js and its plugins is to initialise the SDK and create a scope object that acts on behalf of that type of actor with its API key. In this case, we initialise the SDK by including the scanthng.js plugin and creating an App scope:

// Apply the plugin to the main SDK
EVT.use(EVT.Scan);

const APPLICATION_API_KEY = 'YOUR KEY HERE';
  
// Create scope for working with the application resource
const app = new EVT.App(APPLICATION_API_KEY);

It is this app scope that contains the methods used to perform scanning within the web app, and to retrieve the corresponding resources from the associated EVRYTHNG account.

The recommended way to scan barcodes and identify products within a web app is to use the scanStream() functionality of scanthng.js. This method uses a containing element in your web app to show a styled video stream and then attempt to decode QR codes at regular intervals using jsQR. If one is found the Promise is resolved, and the results can be used as required - either to redirect or show an experience based on the data contained in the identified product or Thng. An example usage of this method is shown below for a web app that has a <div id="stream_container"/> included:

// Scan for 2D QR codes with a video stream within the specified container
app.scanStream({
  filter: { method: '2d', type: 'qr_code' },
  containerId: 'stream_container',
})
  .then(handleResults)
  .catch(alert);

The handleResults function will receive an object that has a standard structure once a barcode is detected (the promise will be resolved). If the decoded QR code contained in any given stream frame is a short URL associated with a product or Thng the results will contain the full object of that resource, as well as a list of redirections available. If not, the meta property will contain the decoded value of the QR code. This could still be a URL but not associated with any EVRYTHNG resource redirection, as is the case with most common QR codes already on consumer packaged goods.

The code example shows one way that these results could be utilised to populate an <a> element that the app user could click on (this is shown in full in the complete example at the end):

const handleResults = (res) => {
  const anchor = document.getElementById('result');
  if (!res.length) {
    // No results
    anchor.innerHTML = 'No results';
    return;
  }

  if (res.length && !res[0].results.length) {
    // Raw URL
    anchor.innerHTML = res[0].meta.value;
    anchor.href = res[0].meta.value;
    return;
  }

  // Full result with redirections
  const url = res[0].results[0].redirections[0];
  anchor.innerHTML = url;
  anchor.href = url;
};

Aside from 2D QR codes, this method can be used for other supported kinds of barcode, but the decoding will happen using the EVRYTHNG API instead of happening within the browser. Depending on your use-case, this is likely still acceptable in order to be able to scan DataMatrix codes from a video stream, for example.

To scan other barcode types with a video stream, simply change the method and type to those required as they appear in the documentation above for the required barcode type. For example, DataMatrix codes:

app.scanStream({
  filter: { method: '2d', type: 'dm' },
  containerId: 'stream_container',
})
  .then(handleResults)
  .catch(alert);

This will then identify all Thngs and products in scope of the authenticated application that have a corresponding value set for the dm identifier.


Conclusion

Hopefully you now have an understanding of the potential benefits of enabling redirections for product digital identities, and an insight into how easy it can be to set up a simple consumer scanning experience. The example demo app provides a simple starting point to developing more complex applications for real-world brands and experiences.

In addition to the redirection capabilities demonstrated here, the Redirector enhances a static redirection into one dynamically based on time, location, demographics, etc.

You can see the complete source code for the example app that was explored in the scanthng-example repository on GitHub.