The days of accidental event duplication are a thing of the past! Enter the Keen Uniqueness Token, an optional property to reject duplicate events and guarantee exactly-once delivery.
What is the Keen Uniqueness Token?
The keen.uniqueness_token is an optional property in the Keen object set by the client. It is an opaque, user-defined string with a max length limit of 64. The Keen platform persists only the very first event it collects with the specific token value, guaranteeing exactly-once delivery. Tokens are scoped per-stream so only duplicate events within a stream will be rejected, not globally. Tokens expire after 31 days, so events with the same token value after this time period may be captured again.
By default, the Keen API accepts an event exactly once, but in the case of disrupted communication, events can be duplicated. All streams that call for exactly-once delivery, a requirement in many business critical applications, will need to use uniqueness tokens. Tokens introduce no difference to the overall performance, so the choice to implement them should be solely based on deliverability requirements.
Why did Keen develop the Uniqueness Token?
The Keen platform accepts an event exactly once by default. In the infrequent case of disrupted communication between your client and the Keen API, an event may be duplicated as shown in the image below.
We recognize the importance of supporting an exactly-once delivery guarantee, especially for applications that require the highest level of data integrity. For example, many financial use cases, like Keen and Chargify’s integrated product, Events-based billing, must only capture billable events once. This is why we’ve created the Keen Uniqueness Token, an optional, user-defined property in the Keen object used to reject duplicate events.
What does it look like in action?
A special keen object is automatically attached to every event when recorded. It contains three standard properties and three optional properties.
The three standard properties include:
- keen.id: A unique ID, used internally to ensure once-only writes.
- keen.created_at: An ISO-8601 timestamp, set at the time each event is recorded.
- keen.timestamp: An ISO-8601 timestamp, set to the same time as keen.created_at unless a value is already present when received
The three optional properties include:
- keen.uniqueness_token: Your unique event ID, used for duplicate prevention. You can read more about event IDs in our data modeling guide.
- keen.location: Enable geo filtering by including a pair of coordinates within keen.location of each event.
- keen.addons: Enable various data enrichment add-ons by passing an array of configuration objects.
Use keen.uniqueness_token for all streams that require exactly-once delivery. We recommend token values to be cryptographic hashes of a list of properties uniquely identifying the event.
For example, in the case of tracking video views, an event representing the “video has been played ” could have the following uniqueness token:
uniqueness_token = sha256(video_identifier + timestamp + user_session_identifier)
Summary
The keen.uniqueness_token is an optional property set by the client in the event body that guarantees an exactly-once delivery by rejecting any duplicate events. Get started for Free and learn more about the uniqueness token by heading to our documentation.
