Merge pull request #5921 from segmentio/trait-updates

rchinn1 · web-flow · commit 1f90666c59ba · 2024-02-07T15:41:16.000-08:00
Add custom traits content
diff --git a/src/_data/sidenav/main.yml b/src/_data/sidenav/main.yml
@@ -341,6 +341,8 @@ sections:
         title: Suggested Predictive Audiences
     - path: '/unify/traits/computed-traits'
       title: Computed Traits
+    - path: '/unify/traits/custom-traits'
+      title: Custom Traits
     - path: '/unify/traits/sql-traits'
       title:  SQL Traits
   - path: /unify/profile-api
diff --git a/src/_includes/content/trait-types.md b/src/_includes/content/trait-types.md
@@ -0,0 +1,14 @@
+## Comparing trait types
+
+View the table below to better understand how Segment collects custom, computed, and SQL traits.
+
+You can use the Profile explorer (**Unify > Profile explorer**) to view traits attached to a profile.
+
+| **Trait type**     |  **Description**          |
+|---------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Custom traits](/docs/unify/traits/custom-traits/)       | Traits created from source events you pass into Segment. From your sources, send custom traits as pieces of information that you know about a user in an Identify call. |
+| [Computed traits](/docs/unify/traits/computed-traits/)     | Traits collected from computations off of event and event property data from your sources. Create user or account-level calculations like `most_viewed_page` or `total_num_orders` for a customer. Learn more by viewing [types of computed traits](/docs/unify/traits/computed-traits/#types-of-computed-traits).    |
+| [SQL traits](/docs/unify/traits/sql-traits/)          | Traits created by running SQL queries on data in your warehouse. SQL traits are a type of computed trait. SQL traits help you import traits from your data warehouse back into Segment to build audiences or enhance data that you send to other destinations. |
+
+<!--
+| [Predictive traits](/docs/unify/traits/predictions/using-predictions/)  |  Segment creates Predictions as Computed Traits, with scores saved to user profiles as a percentage cohort. | -->
diff --git a/src/connections/spec/identify.md b/src/connections/spec/identify.md
@@ -12,7 +12,7 @@ Segment recommends that you make an Identify call:
 - After a user logs in
 - When a user updates their info (for example, they change or add a new address)
 
-The first three examples are pretty self-explanatory, but many might ask: why you would call identify on every page load if you're storing the `userId` in the cookie/local storage?
+The first three examples are pretty self-explanatory, but many might ask: why you would call Identify on every page load if you're storing the `userId` in the cookie/local storage?
 
 Calling Identify in one of Segment's [libraries](/docs/connections/sources/) is one of the first steps to getting started with Segment. Refer to library-specific documentation for more details.
 
@@ -51,6 +51,8 @@ Beyond the common fields, an Identify call has the following fields:
   {% include content/spec-field-user-id.md %}
 </table>
 
+> info ""
+> Note that these traits coming in from your source events are called [custom traits](/docs/unify/traits/custom-traits/).
 
 ## Example
 
@@ -109,7 +111,8 @@ In these cases, you should use an Anonymous ID.
 
 The Anonymous ID can be any pseudo-unique identifier. For example, on your servers you can use a session id. If you don't have any readily available identifier, you can always generate a new random one—Segment recommends [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier){:target="_blank"}.
 
-**Note:** Segment's [browser and mobile libraries](/docs/connections/sources/) **automatically** use Anonymous IDs to keep track of users as they navigate around your website or app, so you don't need to worry about them when using those libraries.
+> info ""
+> Segment's [browser and mobile libraries](/docs/connections/sources/) automatically use Anonymous IDs to keep track of users as they navigate around your website or app, so you don't need to worry about them when using those libraries.
 
 Here's an example of a JavaScript event for an anonymous user:
 
@@ -127,17 +130,19 @@ A User ID is usually the unique identifier that you recognize a user by in your
 
 Segment recommends using database IDs instead of simple email addresses or usernames, because database IDs _never_ change. That guarantees that even if the user changes their email address, you can still recognize them as the same person in all of your analytics tools. And even better, you'll be able to correlate analytics data with your own internal database.
 
-**Instead of using an email address or a username as a User ID, send them along as [traits](/docs/connections/spec/identify#traits).**
+> success ""
+> Instead of using an email address or a username as a User ID, send them along as [custom traits](/docs/unify/traits/custom-traits/).
 
-## Traits
+## Custom traits
 
-Traits are pieces of information you know about a user that are included in an Identify call. These could be demographics like `age` or `gender`, account-specific like `plan`, or even things like whether a user has seen a particular A/B test variation.
+[Custom traits](/docs/unify/traits/custom-traits/) are pieces of information you know about a user that are included in an Identify call. These could be demographics like `age` or `gender`, account-specific like `plan`, or even things like whether a user has seen a particular A/B test variation.
 
-Segment has reserved some traits that have semantic meanings for users, and will handle them in special ways. For example, Segment always expects `email` to be a string of the user's email address. Segment sends this on to destinations like _Mailchimp_ that require an email address for their tracking.
+Segment has reserved some custom traits that have semantic meanings for users, and will handle them in special ways. For example, Segment always expects `email` to be a string of the user's email address. Segment sends this on to destinations like _Mailchimp_ that require an email address for their tracking.
 
-You should **only use reserved traits for their intended meaning**.
+> warning ""
+> Only use reserved traits for their intended meaning.
 
-Reserved traits Segment has standardized:
+Reserved custom traits Segment has standardized:
 
 | **Trait**     | **Type** | **Description**          |
 |---------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -146,7 +151,7 @@ Reserved traits Segment has standardized:
 | `avatar`      | String   | URL to an avatar image for the user  |
 | `birthday`    | Date     | User's birthday         |
 | `company`     | Object   | Company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employee_count` (Number) or `plan` (String) |
-| `createdAt`   | Date     | Date the user's account was first created. Segment recommends using [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) date strings.       |
+| `createdAt`   | Date     | Date the user's account was first created. Segment recommends using [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} date strings.       |
 | `description` | String   | Description of the user |
 | `email`       | String   | Email address of a user |
 | `firstName`   | String   | First name of a user    |
@@ -159,6 +164,7 @@ Reserved traits Segment has standardized:
 | `username`    | String   | User's username. This should be unique to each user, like the usernames of Twitter or GitHub.             |
 | `website`     | String   | Website of a user       |
 
-**Note:** You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a `$created` trait when the user's account was first created, while Intercom recognizes the same trait as `created_at` instead. Segment attempts to handle all the destination-specific conversions for you automatically. If you need help understanding if a specific field will be converted to a destination, take a look at Segment's [open source integration code](https://github.com/segment-integrations?q=&type=all&language=&sort=){:target="_blank"}, view the destination's documentation, or [contact Segment support](https://app.segment.com/workspaces?contact=1).
+> info ""
+> You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a `$created` trait when the user's account was first created, while Intercom recognizes the same trait as `created_at` instead. Segment attempts to handle all the destination-specific conversions for you automatically. If you need help understanding if a specific field will be converted to a destination, take a look at Segment's [open source integration code](https://github.com/segment-integrations?q=&type=all&language=&sort=){:target="_blank"}, view the destination's documentation, or [contact Segment support](https://app.segment.com/workspaces?contact=1){:target="_blank"}.
 
 **You can pass these reserved traits using camelCase or snake_case**, so in JavaScript you can match the rest of your camel-case code by sending `firstName`, while in Ruby you can match your snake-case code by sending `first_name`. That way the API never seems alien to your code base. Keep in mind that not all destinations support these reserved traits, so sending these traits in camelCase and snake_case can result in two sets of traits in other destinations.
diff --git a/src/engage/audiences/index.md b/src/engage/audiences/index.md
@@ -36,9 +36,9 @@ Select `and not who` to indicate users that have not performed an event. For exa
 
 You can also specify two different types of time-windows, `within` and `in between`. The `within` property lets you specify an event that occurred in the last `x` number of days, while `in between` lets you specify events that occurred over a rolling time window in the past. A common use case is to look at all customers that were active 30 to 90 days ago, but have not completed an action in the last 30 days.
 
-### Custom Traits
+### Custom Traits 
 
-You can also build Audiences based on custom traits. These traits can be collected from your apps when a user completes a form or signs up using an [Identify](/docs/connections/spec/identify) call. You can view these traits in the Profile explorer, as well. Custom Traits are mutable and update to the latest value seen by the user's Identify events.
+You can also build Audiences based on [custom traits](/docs/unify/traits/custom-traits/). These traits can be collected from your apps when a user completes a form or signs up using an [Identify](/docs/connections/spec/identify) call. You can view these traits in the Profile explorer, as well. Custom Traits are mutable and update to the latest value seen by the user's Identify events. 
 
 > info ""
 > When an audience that previously generated Identify events is deleted, the data for the audience key is still attached to profiles that entered the audience, and becomes visible in Segment as a custom trait.
diff --git a/src/engage/profiles/csv-upload.md b/src/engage/profiles/csv-upload.md
@@ -55,7 +55,7 @@ A blank subscription status in the CSV doesn't overwrite current **email** or **
 
 Every time you upload a file, you have the option to add a custom trait to user profiles in the CSV. Use custom traits to help you [create audiences](/docs/engage/audiences/#building-an-audience) or send messages to a specific group of users. You can also add an existing custom trait name from your Segment workspace to the list of users in the CSV file.
 
-Custom traits display in the Custom Traits tab of a user profile in the Profile explorer.
+[Custom traits](/docs/unify/traits/custom-traits/) display in the Custom Traits tab of a user profile in the Profile explorer. 
 
 ## View Update History
 
diff --git a/src/unify/Traits/computed-traits.md b/src/unify/Traits/computed-traits.md
@@ -12,6 +12,8 @@ redirect_from:
 
 Computed Traits allow you to quickly create user or account-level calculations that Segment keeps up-to-date over time. These can be computations like the `total_num_orders` a customer has completed, the `lifetime_revenue` of a customer, the `most_frequent_user` to determine which user is most active in an account, or the `unique_visitors_count` to assess how many visitors from a single domain. These computations are based on your events and event properties that you are sending through Segment on the [page](/docs/connections/spec/page/) and [track](/docs/connections/spec/track) calls.
 
+{% include content/trait-types.md %}
+
 ## Types of Computed Traits
 
 Segment currently supports the following types of computed traits:
diff --git a/src/unify/Traits/custom-traits.md b/src/unify/Traits/custom-traits.md
@@ -0,0 +1,82 @@
+---
+title: Custom Traits 
+
+---
+
+Custom traits are user or account traits collected from the Identify calls you send to Segment. For example, these could be demographics like `age` or `gender`, account-specific like `plan`, or even things like whether a user has seen a particular A/B test variation. From your sources, send custom traits as pieces of information that you know about a user in an Identify call.
+
+As opposed to [computed traits](/docs/unify/traits/computed-traits/) which are computed from your source data, or [SQL Traits](/docs/unify/traits/sql-traits/) which are computed from warehouse data, custom traits are created from source events you pass into Segment. 
+
+{% include content/trait-types.md %}
+
+
+## Using custom traits 
+
+Here's the payload of a typical Identify call with custom traits (with most [common fields](/docs/connections/spec/common/) removed):
+
+```json
+{
+  "type": "identify",
+  "traits": {
+    "name": "John Smith",
+    "email": "john@example.com",
+    "plan": "premium",
+    "logins": 5
+  },
+  "userId": "97980cfea0067"
+}
+```
+
+And here's the corresponding JavaScript event that would generate the above payload:
+
+```js
+analytics.identify("97980cfea0067", {
+  name: "John Smith",
+  email: "john@example.com",
+  plan: "premium",
+  logins: 5
+});
+```
+
+> success ""
+> Any source event where there's a `traits` object and key value pairs generates custom traits.
+
+Custom traits are mutable and update to the latest value seen by the user's Identify events. 
+
+When an audience that previously generated Identify events is deleted, the data for the audience key is still attached to profiles that entered the audience and becomes visible in Segment as a custom trait. 
+
+ 
+
+## Reserved custom traits
+
+Segment has reserved some custom traits that have semantic meanings for users, and will handle them in special ways. For example, Segment always expects `email` to be a string of the user's email address. Segment sends this on to destinations like _Mailchimp_ that require an email address for their tracking.
+
+> warning ""
+> Only use reserved custom traits for their intended meaning.
+
+Reserved custom traits Segment has standardized:
+
+| **Trait**     | **Type** | **Description**          |
+|---------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `address`     | Object   | Street address of a user optionally containing:  `city`, `country`, `postalCode`, `state`, or `street`   |
+| `age`         | Number   | Age of a user           |
+| `avatar`      | String   | URL to an avatar image for the user  |
+| `birthday`    | Date     | User's birthday         |
+| `company`     | Object   | Company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employee_count` (Number) or `plan` (String) |
+| `createdAt`   | Date     | Date the user's account was first created. Segment recommends using [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} date strings.       |
+| `description` | String   | Description of the user |
+| `email`       | String   | Email address of a user |
+| `firstName`   | String   | First name of a user    |
+| `gender`      | String   | Gender of a user        |
+| `id`          | String   | Unique ID in your database for a user      |
+| `lastName`    | String   | Last name of a user     |
+| `name`        | String   | Full name of a user. If you only pass a first and last name Segment automatically fills in the full name for you.      |
+| `phone`       | String   | Phone number of a user  |
+| `title`       | String   | Title of a user, usually related to their position at a specific company. Example: "VP of Engineering"                                  |
+| `username`    | String   | User's username. This should be unique to each user, like the usernames of Twitter or GitHub.             |
+| `website`     | String   | Website of a user       |
+
+
+To learn more about using an Identify call to tie custom traits to profiles, [visit Segment's Identify documentation](/docs/connections/spec/identify/).
+
+
diff --git a/src/unify/Traits/sql-traits.md b/src/unify/Traits/sql-traits.md
@@ -61,6 +61,7 @@ This query computes whether a user has an open ticket:
     where t.status in ('pending','open','hold','new')
 ```
 
+{% include content/trait-types.md %}
 
 ## Configure SQL Traits
 
@@ -71,7 +72,7 @@ To use SQL Traits, you need the following:
 - a user account with access to Unify in that workspace
 
 ### Step 1. Set up a warehouse source
-
+ 
 Segment supports Redshift, Postgres, Snowflake, Azure SQL, and BigQuery as data warehouse sources for SQL Traits. Note that the BigQuery setup process _requires_ a service user.
 
 > info "Safeguard your data"
