@provenance/provenance-sdk

Provenance SDK

A library to display Provenance experiences on your website.

Features

• Inserts embeds into the page
• Opens full screen modals for displaying richer Experiences, Stories and Proof Points
• Trust Badge that jumps directly to the Provenance content when clicked

Installation

There are two ways to install the SDK: you can either include it in your JavaScript bundle, or add it as a <script> tag.

Via npm/yarn

npm install --save @provenance/provenance-sdk

yarn add @provenance/provenance-sdk

Via <script> tag

Add this to the bottom of your page, before </body>:

<script type="module" src="https://unpkg.com/@provenance/provenance-sdk@1/dist/main.mjs"></script>

or (no ES module):

<script src="https://unpkg.com/@provenance/provenance-sdk@1/dist/provenance-sdk.js"></script>

Use a <script> tag for faster updates

The Provenance SDK is updated quite frequently with new features and bug fixes. Regardless of the installation method you've chosen, unless you decide to pin to a specific version, you'll automatically receive updates following semantic versioning. However, integrating the SDK via <script> tag is what we recommend, since you'll receive any patches or minor changes as soon as they get released, without having to rebuild your JS bundle. You'll also get all the benefits of using a CDN.

Usage

There are two ways to embed Provenance content:

• directly in HTML, by adding the <provenance> tags to your site;
• using the JavaScript API.

We recommend using HTML tags since they're more straightforward.

Using Provenance HTML tags

Simply add the tag where you want it to appear on the page, replacing the url attribute with the URL of the Provenance experience:

<provenance-experience url="https://www.provenance.org/x/example"></provenance-experience>

Note you can have as many <provenance-experience> embeds as you need in one page, but the SDK should be loaded only once.

You can configure the embed by passing options as HTML attributes.

Using the JavaScript API

Add the embed where you want it to appear on the page:

<provenance-experience url="https://www.provenance.org/x/example"></provenance-experience>

Initialize the embed using the JS snippet below:

import '@provenance/provenance-sdk'

By default this will attempt to find the <provenance-experience> tag and insert an embed there, but you can configure it to suit your needs.

Trust Badge

The Trust Badge shows customers that you have Provenance content enabled on this page. It is a button that, once clicked, will scroll straight to the Provenance content. It is meant to be placed 'above the fold'.

The badge is content-aware, and will only show if Provenance has content to show for that product. You must have product metadata/schema set up in the page for the badge to render. See 'Using Schemas to scope embeds' for details on how to use product schemas.

In order to use it, simply add the tag to your page:

<provenance-trust-badge access-token="{{your_access_token_here}}"></provenance-trust-badge>

Please ask your Provenance representative for an access token. An incorrect or missing access token will cause the badge not to render.

Then add the id="provenance-trust-badge" HTML attribute to the view where you want it to scroll. For example:

<!-- The Trust Badge -->
<provenance-trust-badge></provenance-trust-badge>

<!-- Can scroll to any tag -->
<provenance-bundle id="provenance-trust-badge"></provenance-bundle>

Rendering Proof Point Bundles

If you've added the SDK to your JS bundle, you'll need to import it:

import '@provenance/provenance-sdk'

Then add this tag to your page:

<provenance-bundle url="https://www.provenance.org/bundles/example"></provenance-bundle>

There is no need for you to specify a product ID manually; the SDK will scan your page to search for a product ID and, if found, it will be automatically appended to the URL. Read below for more details on how this works.

Using Schemas to scope embeds

You can use Schemas to scope your bundles or experiences via product or brand. This means that you can use the same URL and embed code on every page, and we automatically determine the correct bundle/experience to display. We support both the Product Schema and the Brand Schema.

When you create a bundle (either via a tag or JavaScript), pass in the schema flag with the name of the schema you want to look for in the page. The case matters, and should be either Brand or Product. E.g.

<provenance-bundle schema="Product" url="https://www.provenance.org/bundles/example">
</provenance-bundle>

or

import { ProvenanceBundle } from '@provenance/provenance-sdk'

// Load Proof Points in <provenance-bundle></provenance-bundle> tag
ProvenanceBundle({
  schema: 'Product',
  url: 'https://www.provenance.org/bundles/example'
})

The SDK will then attempt to find the schema in the page.

How to implement metadata

Your page needs to contain appropriate metadata for the SDK to work. This can be implemented in JSON-LD format. For example:

<script type="application/ld+json">
{
  "@type": "Product",
  "sku": 123456
}
</script>

Alternatively, HTML Microdata encoding is also supported. For example:

<span itemprop="sku">123456</span>

If both are present, we prioritise HTML Microdata as this is only likely to be present if specifically implemented by the site for Provenance to read. We accept both meta tags and regular tags. For example, both <meta itemprop="productID" content="123"> and <span itemprop="sku">123</span> would be accepted.

If the schema cannot be found, nothing will be rendered. If there are multiple schemas in the page, the first schema found will be used.

If you do not specify a schema, and the product or brand ID is not present in the URL, the SDK will look for Product schemas first, then Brand schemas. However, specifying the schema is always recommended. Experiences must have a schema explicitly specified.

Recognised fields in Product Schema

When the SDK is trying to scope a bundle or experience using a Product Schema, it tries to use the following fields as a product ID:

['sku', 'gtin', 'gtin12', 'gtin13', 'gtin14', 'gtin8', 'mpn', 'productID']

The above list is the order of precedence for fields. If multiple fields are present, it will use the higher precedence field.

For example, if only productID and sku are present, sku will be used.

Recognised fields in Brand schema

When the SDK is trying to scope a bundle using a Brand Schema, it just looks at the identifier field. If this field is not present, the SDK won't be able to load the bundle.

Manually loading embeds

The SDK initialises all the embeds it can find in a page by default, as soon as it is imported. However, in some particular cases, you may want to load the embeds manually. For example, if you have a Single Page App and navigate between pages, you may need to reinitialise the Provenance SDK on page change. You can do this with the mountAll function:

import { mountAll } from '@provenance/provenance-sdk'

// Load all Provenance embeds that can be found in the page
mountAll()

The Provenance tags have to be already present in the page for the above to work.

Specifying an HTML container

If you need to use your own HTML element, you can use the container option. For example:

import { ProvenanceExperience } from '@provenance/provenance-sdk'

let myDiv = document.createElement('div')

ProvenanceExperience({ url: '...', container: myDiv })

Rendering a Product Passport

A Provenance Passport shows the journey and impact of a product. These are rendered by the Experience component.

By default, a Passport only needs to know the passportId to render correctly. If you have it, you can initialize a Passport as follows:

<provenance-experience passport-id="my-example-id"></provenance-experience>

or

ProvenanceExperience({ accessToken: '…', passportId: 'my-example-id' })

If you don't have a passportId, you'll need to do a product lookup through our REST API. You can send us either a gtin or a batch identifier. Examples:

<provenance-experience access-token="…" batch="12345678"></provenance-experience>

or

// Product lookup by batch ID
ProvenanceExperience({ accessToken: '…', batch: '12345678' })

// Product lookup by GTIN
ProvenanceExperience({ accessToken: '…', gtin: '12345678', countryCode: 'GB' })

If you pass in a gtin, you can also pass in countryCode to filter manufacturers by country.

Rendering multiple experiences in one page

You can render as many experiences as you need in the same page, however you may not render the same experience twice.

Simply make sure each Experience has its own unique URL. For example:

<provenance-experience url="https://www.provenance.org/x/example-product"></provenance-experience>
<provenance-experience url="https://www.provenance.org/x/example-brand"></provenance-experience>

Alternatively, using the JS API:

<div class="provenance-product"></div>
<div class="provenance-brand"></div>

<script type="module">
import { ProvenanceExperience } from '@provenance/provenance-sdk'

ProvenanceExperience({
  url: 'https://www.provenance.org/x/example-product',
  container: document.querySelector('.provenance-product')
})

ProvenanceExperience({
  url: 'https://www.provenance.org/x/example-brand',
  container: document.querySelector('.provenance-brand')
})
</script>

Handling product variants

Multiple variants of the same product are supported; the way it works depends on your product page.

If the page is fully refreshed on switching variant, you don't need to do anything, the SDK will infer the product identifier from the page metadata.

If the page does not reload when switching between variants (e.g. in case of a Single Page App), you are required to call the setProductID(string) function. This will display the Provenance Proof Points that are relevant to the current product variant.

For example, if your page has a <select id="some_id"> field for choosing a variant, your JavaScript client code might look like this:

import { setProductID } from '@provenance/provenance-sdk'

document.getElementById('some_id')
        .addEventListener('change', e => {
          // Get the current product SKU
          const identifier = /* Provide your product variant here */;

          // Reload Provenance content
          setProductID(identifier);
        });

Alternative way of handling product variants, using CJS

If you would rather not use ESM, you can opt for CJS instead.

The provenance-sdk.js script exposes a Provenance global object that encapsulates all of Provenance functionality. For example:

<!-- Load the CJS build. Put it at the bottom of the page, to ensure the DOM has loaded -->
<script src="https://unpkg.com/@provenance/provenance-sdk@1/dist/provenance-sdk.js"></script>

<script>
  // Attach an event listener to a `<select id="some_id">`
  document.getElementById('some_id').addEventListener('change', e => {
    // Get the current product SKU
    const identifier = 'your_product_identifier_here'

    // Reload content
    Provenance.setProductID(identifier)
  })
</script>

Internationalization

The SDK will simply respect the user's language choice. In other words, the content will be displayed in the language returned by the navigator.language property, which is usually the language of the browser UI.

If the language being requested by the user is a language supported by Provenance, the content will be served in that language. Otherwise, it will fallback to English.

The following languages are supported in the Experiences:

• Danish
• Dutch
• English
• Finnish
• French
• German
• Norwegian
• Polish
• Spanish
• Swedish

Full Specification

If you need more customization, all options are documented below. HTML tags use kebab-case and JS options use camelCase.

Default HTML component

<provenance-experience></provenance-experience>

JavaScript client-side functions

// Initializing Provenance content programmatically
ProvenanceBundle({ options })
ProvenanceExperience({ options })

// Handling product variants
setProductID(identifier)

Available options for initializer functions

Attribute	Description
url	The URL of an Experience to be rendered. It is provided to you by Provenance.
schema	The name of a Schema to scope the experience by.
container	An Element for the embed to be rendered into.
passportId	Passport identifier, typically the slug of the passport.
gtin	GTIN of the product represented by this passport.
countryCode	An ISO 3166-2 country code to filter a passport by. The passport will only filter out manufacturers (and associated supply chain actors) that do not have the specified country code. Use with GTIN, not with batch.
batch	The batch code printed on a can or other product packaging.
accessToken	An API authorization key. Contact Provenance to request one.