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 as well as configure account linking to connect verifications to your own user IDs.

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 the 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 on the Metadata Tracking card 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., customer_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. For example, most account tagging reward strategies rely on knowing a user identifier in order to enable that user to redeem the offer after being verified. In these cases, we support making the key a required key, to reduce the number of customer journey edge cases that you need to account for.

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.

Required keys can often assist with account tagging. Click here to learn more.

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.

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 Share 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. Modify the URL to append 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: