Identity recognition

Real-time identity recognition is how Amperity decides which customer an inbound event belongs to. When an event arrives carrying an identifier–an email address, a loyalty ID, a device identifier–Amperity resolves that identifier to the stitched customer it represents and updates that customer’s real-time profile. Recognition is what connects an anonymous-looking event to the unified customer Amperity already knows.

Two kinds of recognition

An inbound event goes through two distinct recognitions:

  • Event-type recognition decides what kind of event a payload is, so that Amperity can apply the right event type and coerce the event’s fields.

  • Identity recognition decides which customer the event belongs to, by resolving the event’s identifiers to a stitched customer.

This page is about the second. Event-type recognition is covered in About event streams and event types.

From an inbound event to a profile

Once an event has been recognized as a type and coerced, Amperity resolves it to a customer:

  1. Extract the linking keys. Amperity reads the event’s linking keys–the properties assigned a Keychain key on the event type, such as an email address or a cookie ID. Only keys in the collection’s keychain are used, and blank values are skipped.

  2. Route to collections. The event is routed to the profile collections that subscribe to its stream.

  3. Resolve to a profile. Within each collection, Amperity checks every linking-key value on the event against the collection’s keychain. What happens next depends on how many profiles those values belong to:

  4. Update the profile. The event updates the attributes of the profile it resolved to.

An event that carries no linking-key values, and no profile ID, isn’t applied to any profile.

Resolving an event checks every key. A lookup through the Real-time API is different: it tries the keys you send in the collection’s priority order and returns the first profile that matches.

The keychain is a lookup, not live stitching

Real-time recognition does not re-run Stitch on each event. It is a lookup against a keychain built from Stitch’s output. Stitch resolves your customer records into stitched customers, each identified by an Amperity ID, and the keychain maps each linking-key value to the single Amperity ID it resolves to. A value that Stitch associates with more than one Amperity ID is left out of the keychain rather than resolved ambiguously.

The keychain refreshes from Stitch’s output after each run of the collection’s database, when Automatically refresh profiles after each database run? is selected on the collection. Between runs, the keychain grows in real time as events arrive, through just-in-time profile creation and keychain discovery.

Recognize new customers from real-time signals

Recognition does not wait for the next Stitch run to learn about new customers and identifiers. Two mechanisms let Amperity recognize a customer from real-time events alone, before Stitch has seen them.

Just-in-time profile creation

When none of an event’s linking-key values are in the keychain–a first-time visitor, or a customer Stitch hasn’t seen–Amperity creates a profile for them:

  1. Amperity assigns the new profile an Amperity ID and adds the event’s linking-key values to the keychain for that profile.

  2. Amperity holds the event until the new keychain entries are in place, and then applies it to the new profile. A held event is kept for up to two hours.

The new profile is marked as created in real time. Its events update its attributes and its real-time segment memberships like any other profile’s, so a first-time visitor can enter a real-time journey on their first visit.

Keychain discovery

When an event resolves to exactly one profile and also carries linking-key values that aren’t in the keychain yet–a new device, a second email address–Amperity adds those values to that profile’s keychain. Later events that carry only the new value resolve to the same profile.

Discovery never moves a value that already belongs to a different profile. An event that carries values belonging to two profiles is resolved as described in When an event matches more than one profile.

How they work together

Just-in-time profile creation starts a profile from the first identifier Amperity sees, and keychain discovery attaches each identifier that later arrives alongside it. Together they build a customer’s identity from real-time signals alone. For example:

  1. An anonymous visitor browses your website. The event carries only a cookie ID that isn’t in the keychain, so Amperity creates a profile for that cookie ID.

  2. The visitor signs up. The sign-up event carries the cookie ID and an email address. The cookie ID resolves to the new profile, so keychain discovery adds the email address to it.

  3. The customer opens your app and signs in with that email address. The event carries only the email address, which resolves to the same profile, so their app activity and their website browsing build one profile.

Keychain changes are applied shortly after the event that causes them. Two events for a new customer that arrive in quick succession can each start a profile before the first one’s keychain entries are in place. The next event that carries identifiers from both profiles merges them, as described below.

When an event matches more than one profile

An event can carry values that belong to different profiles, such as a sign-in event whose cookie ID belongs to a profile created in real time and whose email address belongs to a customer Stitch already knows. How Amperity resolves it depends on where those profiles came from:

  • Profiles Stitch knows and profiles created in real time. Amperity merges the profiles created in real time into the known profile whose identifier comes first in the collection’s keychain priority order, and the event updates that profile. Any other known profiles the event matches aren’t updated. The merged profiles’ keychain values move to the known profile, their attribute history is combined into its attributes, and the merged profiles are removed, along with their real-time segment memberships. For an hour afterward, events that arrive for a merged profile are redirected to the known profile; after that, they resolve through the keychain values that moved. A merge that hasn’t completed within an hour is dropped.

  • Only profiles created in real time. Amperity merges them into the one whose identifier comes first in the collection’s keychain priority order.

  • Only profiles Stitch knows. Amperity does not merge customers that Stitch resolved separately. The event updates the profile whose identifier comes first in the collection’s keychain priority order, and the next Stitch run decides whether the customers are the same person.

A profile created in real time stays marked that way, even after a Stitch run keeps its Amperity ID. It can still be merged into a profile Stitch knows when an event links the two.

On by default

Just-in-time profile creation and real-time merges are on by default. Amperity can turn either one off for a tenant. With just-in-time profile creation off, an event whose linking-key values match no profile isn’t applied to any profile.

How Stitch reconciles real-time identity

Real-time identity is the best answer Amperity has between Stitch runs. Each Stitch run reconciles it with the rest of your customer data.

Real-time identity feeds Stitch. Each profile created in real time, each identifier added by keychain discovery, and each real-time merge is recorded as a real-time link: a set of identifiers and the profile they belong to. The next Stitch run includes those links alongside your other customer data, so identifiers seen only in real-time events take part in identity resolution. An identifier from an event that matched more than one profile Stitch knows is not sent to Stitch.

Stitch decides each customer’s Amperity ID. How a profile created in real time comes out of a Stitch run depends on what Stitch finds:

  • Only real-time identifiers. When a stitched customer is made up only of real-time links, Stitch keeps the Amperity ID assigned in real time, so the profile carries on as it was. When the stitched customer joins more than one profile created in real time, Stitch keeps the ID with the most links, and the other profiles are removed.

  • Identifiers that belong to customer data. When those identifiers also appear in your other customer data, Stitch resolves them with that data, and the customer data’s Amperity ID wins. The keychain values move to that Amperity ID, and the profile created in real time, left with no keychain values, is removed along with its real-time segment memberships. The customer’s events count toward the stitched customer’s profile.

Profiles are rebuilt from the new identity graph. After each run of the collection’s database, when Automatically refresh profiles after each database run? is selected, Amperity applies the run’s identity changes to the collection:

  • Keychain values move to the Amperity IDs Stitch assigned.

  • Merges, splits, new customers, and removed customers are applied to the collection’s profiles.

  • Event and computed attributes are recalculated from each customer’s full event history under the new identity graph, and real-time segment membership is re-evaluated.

A refresh recalculates attributes from the events up to its cutoff, and then applies the events that arrived after the cutoff to the recalculated profiles. An event that arrived after the cutoff for a profile the refresh removes counts toward the stitched customer’s profile only after a later refresh.

Expect some Amperity IDs to change between runs as Stitch refines its results.

When an event or a lookup doesn’t find the customer you expect, see Troubleshoot real-time.