Skip to content

Commit b7d126f

Browse files
author
markzegarelli
authored
Merge pull request #1136 from segmentio/josephine-liu-1
New Identity onboarding flow [DOC-1]
2 parents fa37cc3 + 3792c72 commit b7d126f

17 files changed

+268
-64
lines changed

‎src/_data/sidenav/main.yml

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ sections:
203203
title: Warehouse FAQs
204204
- path: /connections/storage/warehouses/add-warehouse-users
205205
title: How do you add users?
206-
- path: /connections/storage/warehouses/warehouse-errors
206+
- path: /connections/storage/warehouses/warehouse-errorsx
207207
title: What does my warehouse error mean?
208208
- path: /connections/storage/warehouses/redshift-faq
209209
title: Redshift cluster and Redshift connector limitations
@@ -235,15 +235,17 @@ sections:
235235
slug: personas/personas-identity-resolution
236236
section:
237237
- path: /personas/identity-resolution
238-
title: Identity Resolution Overview
238+
title: Overview
239+
- path: /personas/identity-resolution/identity-resolution-onboarding
240+
title: Onboarding
239241
- path: /personas/identity-resolution/use-cases
240-
title: Identity Resolution Use Cases
242+
title: Use Cases
241243
- path: /personas/identity-resolution/externalids
242-
title: Identity Resolution External IDs
244+
title: External IDs
243245
- path: /personas/identity-resolution/identity-resolution-settings
244-
title: Identity Resolution Settings
246+
title: Settings
245247
- path: /personas/identity-resolution/ecommerce-example
246-
title: Identity Resolution E-Commerce Example
248+
title: E-Commerce Example
247249
- path: /personas/identity-resolution/personas-space-set-up
248250
title: Personas Space Set Up
249251
- path: /personas/computed-traits

‎src/_sass/components/_markdown.scss

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,8 +126,10 @@
126126
margin-bottom: 18px;
127127

128128
@include breakpoint(medium up) {
129-
margin-top: 24px;
130-
margin-bottom: 24px;
129+
border: 1px solid #ddd;
130+
display: block;
131+
margin: 24px auto;
132+
border-radius: 5px;;
131133
}
132134
}
133135

‎src/personas/identity-resolution/externalids.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
---
22
title: Identity Resolution ExternalIDs
33
---
4+
5+
> note ""
6+
> **NOTE:** The steps in this guide pertain to spaces created before September 27th, 2020. For spaces created after September 27th, 2020, please refer to the onboarding guide [here](/docs/personas/identity-resolution/identity-onboarding/).
7+
48
## Default ExternalIDs
59

610
The Identity Graph creates or merges profiles based on externalIDs. ExternalIDs will become the Identities attached to a User Profile in the User Explorer:
711

812
![](images/jane_doe_new_identities.png)
913

10-
We automatically promote the following traits and IDs in track and identify calls to externalIDs:
14+
Segment automatically promotes the following traits and IDs in track and identify calls to externalIDs:
1115

1216
| External ID Type | Message Location in Track or Identify Call |
1317
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
@@ -69,7 +73,7 @@ For example, the following user had anonymous_id and user_id promoted as identif
6973

7074
## Example
7175

72-
Let's say a new anonymous user visits your Pricing page:
76+
For example, a new anonymous user visits your Pricing page:
7377

7478
``` js
7579
analytics.page('Pricing', {
@@ -84,9 +88,9 @@ At this point, the Identity Graph will create a new user with external id (anony
8488

8589
![](images/identity_resolution_2.png)
8690

87-
Any new events received with the same external id (anonymous_id: `anon_123`) will be appended to same user `use_4paotyretuj4Ta2bEYQ0vKOq1e7`.
91+
Any new events received with the same external id (anonymous_id: `anon_123`) are appended to same user `use_4paotyretuj4Ta2bEYQ0vKOq1e7`.
8892

89-
Next, the user goes to a signup form and signs up:
93+
Next, the user goes to a sign up form and signs up:
9094

9195
``` js
9296
analytics.track('User Signup', {

‎src/personas/identity-resolution/identity-resolution-onboarding.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: Identity Resolution Onboarding
3+
---
4+
> note ""
5+
> **NOTE:** The steps in this guide pertain to spaces created after **October 5th, 2020**. For spaces created before **October 5th, 2020**, please refer to[Identity Resolution Settings](/docs/personas/identity-resolution/identity-resolution-settings).
6+
7+
> note ""
8+
> **NOTE:** Workspace owners, Personas administrators, and users with the Identity Admin role can edit Identity Resolution Settings.
9+
10+
Segment creates and merges user profiles based a space's Identity Resolution configuration. Segment searches for identifiers such as `userId`, `anonymousId` and `email` on incoming events and matches them to existing profiles or creates new profiles. These identifiers display in the Identities tab of a User Profile in the User Explorer:
11+
12+
![](images/jane_doe_new_identities.png)
13+
14+
### Flat matching logic
15+
16+
When Personas receives a new event, Segment looks for any profiles that match any of the identifiers on the event.
17+
18+
Based on the existence of a match, one of three actions can occur:
19+
20+
**1: Create a new profile**
21+
When there are no pre-existing profiles that have matching identifiers to the event, Segment create a new user profile.
22+
23+
**2: Add to existing profile**
24+
When there is one profile that matches all identifiers in an event, Segment attempts to map the traits, identifiers and events on the call to that existing profile. If there is an excess of any identifier on the final profile, Segment defers to the Identity Resolution rules outlined below.
25+
26+
**3: Merge existing profiles**
27+
When there are multiple profiles that match the identifiers in an event, Segment checks the Identity Resolution rules outlined below, and attempts to merge profiles.
28+
29+
## Identity Resolution settings
30+
31+
Identity Admins should first configure Identity Resolution Settings page to protect the identity graph from inaccurate merges and user profiles.
32+
33+
During the space creation process, the first step is to choose an Identity Resolution configuration. If this is your first space, you have the option to choose a Segment-suggested Out-of-the-Box configuration or a custom Identity Resolution setup. All other spaces have a third option of importing settings from a different space.
34+
35+
![](images/first_screen.png)
36+
37+
### Out-of-the-Box
38+
39+
For most first-time Personas users, Segment recommends that you use the out-of-the-box configuration and answer a short series of questions for a best-fit setup for your use-case.
40+
41+
If you have custom unique identifiers or do not have a canonical `user_id` are automatically redirected to the Identity Resolution Settings page to complete your setup.
42+
43+
### Custom rules
44+
45+
If you are familiar with identity or have custom identifiers, Segment recommends that you select Custom Rules.
46+
47+
Segment redirects you to the Identity Resolutions Settings page where you can add Default Identifiers or Custom Identifiers.
48+
49+
Segment's 11 default are:
50+
51+
| External ID Type | Message Location in Track or Identify Call |
52+
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
53+
| `user_id` | userId |
54+
| `email` | traits.email or context.traits.email |
55+
| `android.id ` | context.device.id when context.device.type = 'android' |
56+
| `android.idfa` | context.device.advertisingId when context.device.type = 'android' AND context.device.adTrackingEnabled = true |
57+
| `android.push_token` | context.device.token when context.device.type = 'android' |
58+
| `anonymous_id` | anonymousId |
59+
| `ga_client_id` | context.integrations['Google Analytics'].clientId when explicitly captured by users |
60+
| `group_id ` | groupId |
61+
| `ios.id ` | context.device.id when context.device.type = 'ios' |
62+
| `ios.idfa` | context.device.advertisingId when context.device.type = 'ios' AND context.device.adTrackingEnabled = true |
63+
| `ios.push_token` | context.device.token when context.device.type = 'ios' |
64+
65+
You can also provide a trait or property key to match on to add custom identifiers. You can preview the locations where Segment looks for the identifier. Segment accepts both camelCase and snake_case for context.traits, traits and properties, but accepts lowercase types for identifiers only in the context.externalIds object.
66+
67+
![](images/custom_identifiers.png)
68+
69+
#### Blocked values
70+
71+
Segment recommends that you proactively prevent using certain values as identifiers. While these values remain in the payload on the event itself, it os not promoted to as an identifier Segment uses to determine user profiles.
72+
73+
This is important when developers have a hard-coded value for fields like `user_id` during QA or development that then erroneously make it production. This may cause hundreds of profiles to merge incorrectly and can have costly consequences if these spaces already feed data into a production email marketing tool or push notification tool downstream.
74+
75+
In the past, Segment has seen certain default values that cause large amounts of profiles to merge incorrectly. Segment suggests that for every identifier, customers opt into automatically blocking the following suggested values:
76+
77+
| Value | Type |
78+
| ----------------------------- | --------------- |
79+
| Zeroes and Dashes (`^[0\-]*$) | Pattern (REGEX) |
80+
| -1 | Exact Match |
81+
| null | Exact Match |
82+
| anonymous | Exact Match |
83+
84+
![](images/blocked-values.png)
85+
86+
Before sending data through, Segment also recommends that you add any default hard-coded values that your team uses during the development process, such as `void` or `abc123`.
87+
88+
#### Limit
89+
90+
Identity Admins can specify the total number of values allowed per identifier type on a profile during a certain period. For example, in the image below, the `anonymous_id` field has a limit of **5 Weekly**.
91+
![](images/anonymous-id.png)
92+
93+
This will vary depending on how companies define a user today. In most cases, companies rely on `user_id` to distinguish user profiles and Segment defaults to the following configurations:
94+
95+
| Identifier | Limit |
96+
| --------------------- | ----- |
97+
| user_id | 1 |
98+
| all other identifiers | 5 |
99+
100+
Specific cases may deviate from this default. For example, a case where a user can have more than one `user_id` but one email, like when `shopify_id` and an internal UUID define a user. In this case, an example configuration may be:
101+
102+
| Identifier | Limit |
103+
| --------------------- | ----- |
104+
| email | 1 |
105+
| user_id | 2 |
106+
| all other identifiers | 5 |
107+
108+
When you choose the limit on an identifier, ask the following questions about each of the identifiers you send to Segment:
109+
110+
1. Is it an immutable ID? An immutable ID, such as `user_id`, should have `1 ever` per user profile.
111+
2. Is it a constantly changing ID? A constantly changing ID, such as `anonymous_id` or `ga_client_id`, should have a short sliding window, such as **5 weekly** or **5 monthly**, depending on how often your application automatically logs out the user.
112+
3. Is it an ID that updates on a yearly basis? Most customers will have around 5 emails or devices at any one time, but can update these over time. For identifiers like `email`, `android.id` or `ios.id`, Segment recommends a longer limit like **5 annually**.
113+
114+
#### Priority
115+
116+
Segment considers the priority of an identifier once that identifier exceeds the limit on the final profile.
117+
118+
For example, consider a Personas space with the following Identity Resolution configurations:
119+
120+
| Identifier | Limit | Priority |
121+
| ------------ | ----- | -------- |
122+
| user_id | 1 | 1 |
123+
| email | 5 | 2 |
124+
| anonymous_id | 5 | 3 |
125+
126+
A profile already exists with `user_id` **abc123** and `email` **[email protected]**. A new event comes in with new `user_id` **abc456** but the same `email` **[email protected]**.
127+
128+
If this event maps to this profile, the resulting profile would then contain two `user_id` values and one `email`. Given that `user_id` has a limit of 1, this exceeds the limit of that identifier. As a result, Segment checks the priority of the `user_id` identifier. Because `email` and `user_id` are the two identifiers on the event and `email` ranks lower than `user_id`, Segment demotes `email` as an identifier on the incoming event and tries again.
129+
130+
At this point, the event searches for any profiles that match just the identifier user_id `abc456`. Now there are no existing profiles with this identifier, so Segment creates a new profile with user_id `abc456`.
131+
132+
By default, Segment explicitly orders user_id and email as rank `1` and `2`, respectively. All other identifiers are in alphabetical order beginning from rank `3`. This means that if the identifiers sent with events flowing into personas are user_id, email, anonymous_id and ga_client_id, the rank would be as follows:
133+
134+
| Identifier | Priority |
135+
| ------------ | -------- |
136+
| user_id | 1 |
137+
| email | 2 |
138+
| anonymous_id | 3 |
139+
| ga_client_id | 4 |
140+
141+
If a new android.id identifier appeared without first giving it explicit order, the order would automatically reshuffle to:
142+
143+
| Identifier | Priority |
144+
| ------------ | -------- |
145+
| user_id | 1 |
146+
| email | 2 |
147+
| android.id | 3 |
148+
| anonymous_id | 4 |
149+
| ga_client_id | 5 |
150+
151+
If you require an explicit order for all identifiers, configure this in the Identity Resolution settings page before sending in events.
152+
153+
![](images/edit-priority.png)
154+
155+
When choosing the priority of your identifier, ask the following questions about each of the identifiers you send to Segment:
156+
157+
1. Is it an immutable ID? Give immutable IDs, such as user_id, highest priority.
158+
2. Are they unique IDs? Give Unique IDs such as email higher priority than possibly shared identifiers like android.id or ios.id.
159+
3. Does it temporarily identify a user? Identifiers such as anonymous_id, ios.idfa, ga_client_id are constantly updated or expired for a user. Generally speaking, rank these lower than identifiers that permanently identify a user.
160+
161+
### Importing from an existing space
162+
163+
This option is available to new spaces after you create an initial Dev space. Segment recommends this option when identity settings are validated as correct in the initial Dev space and should be copied into the Production space.
164+
165+
You can review the identifiers, priorities, limits, and blocked values before you complete the import.
166+
167+
![](images/import.png)
168+
169+
## Connect a source
170+
171+
After you configure Identity Resolution settings, the next step is to connect a [source](/docs/connections/sources/) to the Personas space.
172+
173+
## Create an Audience
174+
175+
After you connect a source, Personas creates user profiles based off of replayed and newly incoming data.
176+
177+
![](images/create_audience.png)
178+
179+
The next step, which is important in the Dev space, is to create an audience to ensure that user profiles have populated correctly and that the identity resolution settings follow expected business logic.
180+
181+
For example, if there should be 100,000 distinct users who have a `user_id`, this would be a great way to validate that the identity resolution settings have calculated profiles correctly.
182+
183+
For more information about how to create audiences and traits, see [Audiences](/docs/personas/audiences/).

0 commit comments

Comments
 (0)