Tracking custom metadata

Metadata allows you to pass additional key-value pair data with your verification, e.g., "status": "platinum" or "promotion": "back_to_school".

This can help you track various datapoints. To enforce a consumer having to be logged in, pease see our article, Passing a consumer's account ID.

To incorporate metadata you must:

1. Add the key(s) in the Metadata Tracking card in your program settings, so that your program knows to save these values
2. Update the URL that calls SheerID, to append the metadata as parameters

WARNING: Never send personally identifiable information (PII) to SheerID as campaign metadata, other metadata, or in URL parameters. Any metadata you pass to SheerID in these ways should refer to campaigns or other items of interest, not individuals. PII should only be submitted to SheerID in verification subject JSON body (or through our verification forms), to ensure this data is processed subject to the relevant privacy and security controls. If you must store metadata associated with an individual, it is your responsibility to encrypt and/or tokenize that information before storing it as verification metadata.

Where to add keys

1. Login to your MySheerID account, and select the program you wish to edit

2. Click on the Settings button

   

3. On the Settings page, click +Add button to open the dialog box

   

4. Click the toggle switch to On to enable Metadata Tracking

   

SheerID recommends using lowercase letters (and optionally underscores) when defining your keys, e.g., promotion_id. The keys and the corresponding values will be passed to SheerID in the URL of the verification, and are meant to be human-readable when reviewing reporting data. Including special characters in your key may result in avoidable parsing errors.

Required vs optional keys

Required keys

Sometimes it is essential that every verification has a value for one (or more) of the keys you specified. 

If a key is required, but missing a value, then the verification form will show an error. You can modify this error message to provide instruction to your customer on how to rectify the situation.

In the example below, this URL is missing the required key and therefore loads the error message:

With the key appended to the URL the form will load and upon submission the metadata will be associated with the verification and found in reporting.

Optional keys

If metadata is for performance tracking or "nice to know," then SheerID recommends keeping the key optional so as not to cause friction for users trying to verify.

Custom metadata in the Shopify app

In our Shopify app theme extension, we collect the "customer_id" from the Shopify page and add it as a query parameter to the verification URL. Any parameters that you collect in the Shopify app will need to be manually added to the verification URL using the standard program configurations.

The "customer_id" from Shopify is not a reliable way to access a consumer's ID if they are not logged in to your Shopify store before checking out. We recommend tagging Shopify customers and orders using the Shopify Flow app. However, Shopify will populate "customer_id" with a value now with guest checkouts. We collect this ID from the following places to add to the verification URL:

• window.ShopifyAnalytics.meta.page.customerId
• window.meta.page.customerId
• ShopifyAnalytics.lib.user().traits().uniqToken

Updating the offer URL with metadata parameters 

Once you've added and saved your metadata keys you will need to modify the offer URL to append the metadata as parameters. 

How to format the offer URL

Wherever the verification URL is used — whether in a code snippet or linked directly as a CTA — you will want to include the metadata key-value pair in the following format:

Understanding the URL components

• ?custom_key= is the metadata key that defines the data your brand wants to pass to SheerID with each verification.
•  ${customValue} is the value that your brand assigns to that metadata key, which will be stored with each verification.

Publishing the form with the updated URL

If you're using SheerID's code to publish your offer, follow these steps:

1. Click Embed on the program overview page

   

2. Choose how you want to load the form:
   • Pop-up form
   • Embedded form
   • Landing page

3. In your selected method, locate the offer URL

   

4. The URL will be automatically appended with the metadata key-value pair as you publish the code on your site

Without adding the metadata parameters, the data will not be passed to SheerID correctly. Ensure that the updated URL is used everywhere the verification form is implemented. To see an alternate method to set metadata, read more in our Developer Center.

Static vs dynamic metadata

Static metadata always contains a constant datapoint.

In the example below you'll find a static key appended to the URL. The key "promotion" will always return back_to_school.

Dynamic

When you have data that will change based on variables, you can configure dynamic metadata values. Your web developer will define a custom variable, set it for a given site visitor by pulling from the source you specify, and pass that into the URL calling SheerID's verification form as shown in the example below: