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

8006 / itip

gs1:8006

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 or itip.

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.


GS1 Digital Link 1.1 support

📘

Note

GS1 Digital Link 1.1 support is in beta - we may make significant changes before the final version.

If you are interested in using these features, please contact us so we can enable it for your account.

Enable Digital Link 1.1. 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.

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.

GS1 Digital Link 1.1 LinkType support

Since version 1.1, the GS1 Digital Link standard supports using a query parameter called linkType. This allows applications to request specific content for a particular GTIN, GRAI, GLN or any other standard GS1 identifier. Imagine for instance an application wanting to get nutritional facts about a product given its GTIN. With linkType this can be done in a standard way by adding: linkType=gs1:nutritionalInfo to the Digital Link URL.

To use this with the EVRYTHNG Product Cloud, simply create Redirector rules that react to this parameter by using "GS1 Digital Link: Link Type is" as in the example below:

With this rule applications can now request nutritional facts for GTIN 09520246813579 by appending the linkType query string parameter, for example:
https://pb.tn.gg/01/09520246813579?linkType=gs1:nutritionalInfo.

The possible values of the linkType parameter are specified in the GS1 Digital Link 1.1 standard. This allows applications to know what information they can request and how, this ultimately creates a universal standard for apps and web apps to request information about a product.

The values should be derived from either the GS1 Web vocabulary or schema.org. If neither of those are suitable, the standard allows you to use your own URI which should dereference to information about the relationship. For instance: linkType=myBrand:myLinkType.

Header parameters

You can also dynamically redirect users based on their header parameters. Currently, the following are supported:

  • Accept
  • Accept-Language
  • User-Agent

When triggering redirections based on header parameters, you can match using three different techniques:

  • Exact: Use is followed by the full header string that you want to match
  • Wildcard: Use is and add a wildcard * to the beginning and/or end of the string. For example *en* will match on any string containing "en", such as "fr-FR,en-GB;q=0.9,en;q=0.8"
  • Regular Expression: Use matches (regex) and regular expression syntax to describe your criteria. For example, the screenshot below shows a regex designed to redirect only when a code is scanned on a mobile device using Android or iOS.

Updated 11 days 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.