GS1 Digital Link

The EVRYTHNG Platform supports the GS1 Digital Link format, which allows a single 2D barcode to provide point of sale functionality and also behave as a consumer-facing web-based URL at the same time to drive a consumer experience.

By adding standard GS1 Application Identifiers to EVRYTHNG Thngs and products, it becomes possible to easily configure support for a corresponding GS1 Digital Link. Adding on a redirection or Redirector rules allows any consumer who scans the 2D barcode to be dynamically redirected to a rich product experience while at the same time providing additional value to the brand before retail.

GS1 Digital Link Tools

You can quickly and easily get started using the GS1 Digital Link with our generator and verifier tools, which allow you to create a complete and valid GS1 Digital Link, as well as validate any others you may have already.

The tools use our digital-link.js JS library that allows easy creation, manipulation, and validation of GS1 Digital Links in code.


Supported Application Identifiers

The list below details the GS1 Application Identifiers that are currently supported for redirection when specified as part of the identifiers on a Thng or product. Note that all GS1-specified identifier keys are namespaced with the gs1 prefix.

Product Identifiers

AI / Short Name Alias
`identifiers` key
Note

01 / gtin

gs1:01

Must be stored as a GTIN-14. For example, an EAN must be zero padded.

22 / cpv

gs1:22

Only valid with a gtin.

8010 / cpid

gs1:8010

Thng Identifiers

AI / Short Name Alias
`identifiers` key
Note

10 / batch or lot

gs1:10

Only valid with a serial.

21 / serial or ser

gs1:21

Only valid with a gtin.

8011 / cpsn

gs1:8011

Only valid with a cpid.

00 / sscc

gs1:00

Only valid by itself.

8003 / grai

gs1:8003

Only valid by itself.

8004 / giai

gs1:8004

Only valid by itself.


GS1 Domains

As part of the GS1 Digital Link Integration, each account is assigned a short domain of the form abcde.tn.gg, where abcde is a five character random string. This short domain is used for the generation and redirection of GS1 Digital Links. This domain can be discovered with a Read all Domains request.

Custom Domains

In addition to the built-in short domain detailed above, we also offer the ability to name your short domain, or even use your own company domain entirely.

Please contact us to find out more about this Enterprise feature.


Add a GS1 Digital Link for a Product

Note

A Thng configured as described below will only have a corresponding GS1 Digital Link and QR code if it also has a redirection already set.

To enable the GS1 Digital Link integration for an EVRYTHNG Platform product, simply ensure that the following are true:

  • The Thng has a redirection set.
  • At least one Application Identifier (such as gs1:21 for a serial) is added to the Thng.
  • At least one Application Identifier (such as gs1:01 for a GTIN) is added to a product.
  • The Thng is linked to the product via its product property.

For example, see the identifiers of the example product and Thng resources below:

{
  "id": "U5c5GHUGVqsNt7www3c5Nc2s",
  "createdAt": 1529584185752,
  "updatedAt": 1529584185752,
  "fn": "Can of Beans",
  "name": "Can of Beans",
  "identifiers": {
    "gs1:01": "05000157089908"
  }
}
{
  "id": "U5yK3HkbBMP7trwRaGy5Qr3p",
  "createdAt": 1529584257929,
  "updatedAt": 1529584257929,
  "name": "Single can of beans",
  "product": "U5c5GHUGVqsNt7www3c5Nc2s",
  "identifiers": {
    "gs1:21": "347834"
  }
}

Once these two pieces of data are in place, and the account short domain is identified, the corresponding GS1 Digital Link that redirects to this Thng will be:

https://abcde.tn.gg/gtin/:gtin/ser/:ser

Notes

  • Alias values for Application Identifiers (for example, gtin instead of gs1:01) are only valid in Digital Link URLs.
  • Any attempt to access a GS1 Digital Link URL that does not produce a product or Thng will redirect to the account's defaultUrl, if it is set.

For example, the above product and Thng resources will have the following GS1 URI for the serialised Thng:

https://wrxfq.tn.gg/gtin/5000157089908/ser/347834

and the equivalent product only redirection:

https://wrxfq.tn.gg/gtin/5000157089908

GTIN padding

You might notice in the above URLs that the leading 0 is missing from the gtin. To make your digital link URL shorter, you can drop the leading 0s. When we do a lookup for that GTIN, we will add the 0s back in before looking up the EVRYTHNG product.


GS1 Digital Link in the Dashboard

Once a product and one or more Thngs are correctly configured (as described above), the EVRYTHNG Dashboard will automatically display the equivalent GS1 Digital Link both as a URL and as a QR code.

The example Thng above would therefore look similar to the one shown below:


Generate a GS1 Digital Link QR Code

Using the existing functionality to generate a QR code it is also possible to generate a QR code that encodes the GS1 Digital Link (including any redirections present). To do this, make a request for the PNG including the gtin and ser (if applicable) in the URL, as well as optional width (w) and height (h) values. An example is shown below:

GET https://wrxfq.tn.gg/gtin/5000157089908/ser/347834.png?w=256&h=256
Accept: image/png
curl -X GET 'https://wrxfq.tn.gg/gtin/5000157089908/ser/347834.png?w=256&h=256' \
  -H "Accept: image/png" > ./gs1_code.png

The result will look similar to a normal short URL QR code, but will instead encode the GS1 Digital Link, ready for scanning by industrial/point of sale and consumer applications alike.


Enable Digital Link Compression

EVRYTHNG also offer a GS1 Digital Link compression domain allowing smaller URLs to be encoded into QR codes and still be resolved. In turn, the QR codes become less dense and therefore more readable at smaller sizes.

Note

This first support of GS1 Digital Link compression is a beta capability - we may make significant changes before the final version.

If you are interested in using this feature, please contact us!

Enabling Compressed URIs

Once you have completed the steps above to add a GS1 Digital Link URI to a product or Thng, use either the digital-link.tools page or digital-link.js to compress it. For example, a product with GTIN 00789968000023 in an account with the wrxfq.tn.gg domain:

https://wrxfq.tn.gg/01/789968000023

Once compressed, this becomes:

https://wrxfq.tn.gg/AQFv24YoLg

The final step required to support the compressed URI is to substitute the domain tn.gg for g1.je which is specialised for this purpose. Thus the value to be encoded in a QR code:

https://wrxfq.g1.je/AQFv24YoLg

Using Compressed URIs

When a QR code on packaging is scanned and contains a compressed GS1 Digital Link URI, the g1.je domain decompresses and resolves to the original domain tn.gg:

https://wrxfq.g1.je/AQFv24YoLg >> https://wrxfq.tn.gg/01/789968000023

From then on, the regular resolution process continues to send the user to the product or Thng's redirection.

Updated 3 months ago

GS1 Digital Link


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.