Search documentation...

K
ChangelogBook a demoSign up

Managing contracts

Hightouch Contracts helps marketing and data teams plan, manage, and enforce the data they track through event collection.

Contracts have two components::

  • A contract event defines the name, type, description, and validation schema of a single event (for example, Order Completed)
  • The contract is a set of contract events that can be applied to an event source (for example, E-commerce Events)

Each contract event can only belong to a single contract, but a contract can be applied to multiple event sources.

Event definition

The most important part of creating a contract event is defining the validation schema. Hightouch uses JSONSchema to define rules for validating the event payload.

When creating an event, you can either use our visual editor to define a JSONSchema, or paste a custom schema definition into Hightouch.

Event creation screenshot

Hightouch uses JSONSchema Draft 7. This allows for highly complex validation of event payloads, including validating field values with regular expressions.

Event versioning

Hightouch allows you to manage different versions of an contract event at the same time. This is often useful when it is difficult to migrate your codebase to use the latest payload. For example, when an iOS app takes a while to be updated across all devices.

After creating your first event, you can create additional versions of the schema. The first version is the "default" version, which applies to events that do not specify a version in the payload. It is recommended that your events follow an incrementing pattern (for example, v1, v2, v3), although not strictly required.

Event versioning screenshot

When invoking an event, you can specify the schema version via:

client.track('Order Completed', {
  ...
}, {
  context: {
    protocols: {
      schemaVersion: "v2"
    }
  }
});

If your schema version is specified on a different field (for example, context > ... > event_version), you can customize the path at the contract level.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Oct 16, 2023

On this page

Was this page helpful?