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 act 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, you can 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, providing additional value to the brand before retail.

📘

GS1 Digital Link Tools

Get started using the GS1 Digital Link with our generator and verifier tools, which lets you create a complete and valid GS1 Digital Link, as well as validate any others.

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. All GS1-specified identifier keys are namespaced with the gs1 prefix.

Product Identifiers

Thng Identifiers

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 generating and redirecting GS1 Digital Links. This domain can be discovered with a Read all Domains request.

📘

Custom Domains

Besides 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.

Contact us to find out more about this Enterprise feature.

Add a GS1 Digital Link for a Product or Thng

🚧

Warning

A Thng or Product configured as described below only has a corresponding GS1 Digital Link and QR code if it also has a Redirection set.

To enable the GS1 Digital Link integration for an EVRYTHNG Platform resource, simply set an identifier on the resource per the above tables.

• For a GS1 Digital Link that has only a GTIN, set the Product identifier.
• For a GS1 Digital Link that has a serialized GTIN, set both the Product and Thng identifiers.

For example, for an SGTIN (Serialized GTIN), you would need to ensure the following:

• The Thng has a Redirection set.
• An Application Identifier gs1:21 for the Serial is added to the Thng.
• An Application Identifier gs1:01 for the 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": "U5FfewD3t9HBmXwwaG29daxq",
  "createdAt": 1529584185752,
  "updatedAt": 1529584185752,
  "fn": "GS1 Bear Blog Edition",
  "name": "GS1 Bear Blog Edition",
  "identifiers": {
    "gs1:01": "99507000009060"
  }
}

{
  "id": "UKkfeartMm9C8Hawa2DMnGss",
  "createdAt": 1529584257929,
  "updatedAt": 1529584257929,
  "name": "Jim the Bear Blogger",
  "product": "U5FfewD3t9HBmXwwaG29daxq",
  "identifiers": {
    "gs1:21": "02043"
  }
}

After 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 is:

https://abcde.tn.gg/01/:gtin/21/:serial

📘

Notes

• As of version 1.2 of the standard, alias values are no longer supported. Use only the numeric version of the key, for example, 01 rather than gtin.
• Any attempt to access a GS1 Digital Link URL that doesn't produce a product or Thng redirects to the account's defaultUrl, if it's set.

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

https://dfnnr.tn.gg/01/99507000009060/21/02043

and the equivalent product only redirection:

https://dfnnr.tn.gg/01/99507000009060

👍

GTIN Padding

To make your digital link URL shorter, you can drop the leading zeroes from any GTIN. For example, if the GTIN is 00614141123452, drop the first two zeroes, leaving 01/614141123452. When we do a lookup for that GTIN, we replace the zeroes before looking up the EVRYTHNG product.

GS1 Digital Link in the Dashboard

After a product and one or more Thngs are correctly configured, the EVRYTHNG Dashboard automatically displays the equivalent GS1 Digital Link as a URL and as a QR code.

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

Generate a GS1 Digital Link QR Code

Using the existing functionality to generate a QR code, you can also 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 01 and 21 (if applicable) in the URL, as well as optional width (w) and height (h) values:

GET https://dfnnr.tn.gg/01/99507000009060/21/02043.png?tpl=default&w=256&h=256
Accept: image/png

curl -X GET 'https://dfnnr.tn.gg/01/99507000009060/21/02043.png?tpl=default&w=256&h=256' \
  -H "Accept: image/png" > ./gs1_code.png

The result looks similar to a normal short URL QR code but instead encodes the GS1 Digital Link, making it ready for scanning by industrial/point of sale and consumer applications.

GS1 Digital Link compression

📘

Note

Compression support is in beta. We might make changes before the final version.

If you are interested in using these features, contact us to enable it for your account.

Enable Digital Link 1.1. Compression

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

Enabling Compressed URIs

After you've completed the steps above to add a GS1 Digital Link URI to a product or Thng, use 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

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 specialized for this purpose. The value to be encoded in a QR code is:

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.

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 example, you want your application to get nutritional facts about a product given its GTIN. With linkType, you can do this by adding: linkType=gs1:nutritionalInfo to the Digital Link URL.

To use this with the EVRYTHNG Product Cloud, 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 you to know what information your application can request and how. This ultimately creates a universal standard for apps and web apps to request information about a product.

We recommend the values 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 contain information about the relationship. For instance: linkType=myBrand:myLinkType.

Retrieving All linkTypes for a Resource

If you add ?linkType=all to your URL, you can retrieve all available linkTypes for a given resource. The response format uses the draft IETF linkset standard, as in the example below.

GET https://dfnnr.tn.gg/01/99507000009060/21/02043?linkType=all

{
    "linkset": [
        {
            "anchor": "https://dfnnr.tn.gg/01/99507000009060/21/02043",
            "itemDescription": "Jim the Bear Blogger",
            "https://gs1.org/voc/defaultLink": [
                "https://evrythng.com/blog/"
            ],
            "https://gs1.org/voc/promotion": [
                {
                    "href": "https://evrythng.com/consumer-engagement/",
                    "Language": "en",
                    "Title": "2 for 1 offer on Bears!"
                }
            ],
            "https://gs1.org/voc/review": [
                {
                    "href": "https://evrythng.com/customer-stories/",
                    "Language": "en",
                    "Title": "EVRYTHNG Case Studies"
                }
            ]
        },
        {
            "anchor": "https://dfnnr.tn.gg/01/99507000009060",
            "itemDescription": "GS1 Bear Blog Edition",
            "https://gs1.org/voc/defaultLink": [
                "https://www.evrythng.com/blog"
            ],
            "https://gs1.org/voc/review": [
                {
                    "href": "https://evrythng.com/customer-stories/",
                    "Language": "en",
                    "Title": "EVRYTHNG Case Studies"
                }
            ]
        }
    ]
}

📘

Note

Any constants you add to your redirection rule are also returned in the linkset, such as the Language and Title attributes in the above example.

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 you want to match
• Wildcard: Use is and add a wildcard * to the beginning or end of the string or both. For example, *en* matches 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.

Fallback Rules for Non-Existent Resources

If a client sends a request to get a non-existent resource, per the Digital Link standard, we fall back to the parent resource. For example, if the client requests:

https://dfnnr.tn.gg/01/99507000009060/21/98765

Here, no Thng with a gs1:21 identifier value of 98765 exists. Instead of returning a 404 Not Found response, we fall back to the Product, in this case with a gs1:01 identifier value of 99507000009060.

Finally, if the Product didn't exist, we would fall back to the default URL for the Account (configure this by setting a URL value on the account.defaultUrl attribute).