Merge pull request #360 from segmentio/repo-sync

repo sync

Author: bot-docsteam

src/personas/audiences/index.md

@@ -53,6 +53,9 @@ See [Account-level Audiences](/docs/personas/audiences/account-audiences) for mo
 
 ## Connecting your Audience to a Destination
 
+> warning "Audience Keys"
+> Avoid using the same Audience key twice, even if you've deleted the original Audience.
+
 Once you have previewed your audience, you can choose to connect a destination, or simply keep the audience in Segment and download a csv. If you already have destinations set up in Segment, you can import the configuration from one of your existing sources to Personas. Note that you can only connect one destination configuration per destination type.
 
 ![](/docs/personas/images/audience_select_destination_card.png)

src/personas/faqs.md

@@ -5,16 +5,16 @@ title: Personas Frequently Asked Questions
 
 
 ## Can I use the Profile API on the client-side?
-For security reasons, we require the Profile API only be used server-side. The Profile API allows you to look up data about any user given an identifier (e.g. email, `anonymousId`, or `userId`) and an authorized access secret. While this enables powerful personalization workflows, it could also let your customers' data fall into the wrong hands if the access secret were exposed on the client.
+For security reasons, Segment requires that the Profile API only be used server-side. The Profile API allows you to look up data about any user given an identifier (for example, email, `anonymousId`, or `userId`) and an authorized access secret. While this enables powerful personalization workflows, it could also let your customers' data fall into the wrong hands if the access secret were exposed on the client.
 
 Instead, by creating an authenticated personalization endpoint server-side backed by the Personas Profile API, you can serve up personalized data to your users without the risk of their information falling into the wrong hands.
 
 
 ## Do you have an Audiences API?
 
-Currently you can add, remove, and modify audiences only by using the Personas in-app audience builder.
+You can add, remove, and modify audiences only by using the Personas in-app audience builder.
 
-However, you can programmatically query the Profile API in order to determine if a particular user is a member of a particular audience because Personas creates a trait with the same name as your audience. For example, to determine if the user with an email address of `[email protected]` is a member of your `high_value_users` audience, you could query the following profile API URL:
+However, you can programmatically query the Profile API to determine if a user belongs to a particular audience because Personas creates a trait with the same name as your audience. For example, to determine if the user with an email address of `[email protected]` is a member of your `high_value_users` audience, you could query the following profile API URL:
 
 `https://profiles.segment.com/v1/namespaces/<namespace_id>/collections/users/profiles/email:[email protected]/traits?include=high_value_users`
 
@@ -31,8 +31,11 @@ The following response indicates that Bob is indeed a high-value user:
 }
 ```
 
-To learn more about our profile API, you can head [here](https://segment.com/docs/personas/profile-api).
+For more information on profile queries, visit the [Profile API documentation](/docs/personas/profile-api).
 
+## Can I reuse audience keys?
+
+Avoid using the same audience key twice, even if you've deleted the key's original audience. Downstream tools and Destinations might have trouble distinguishing between different audiences that at any point shared the same key.
 
 ## Does your identity model support multiple external ID types?
 
@@ -68,23 +71,23 @@ The trait and audience will automatically update going forward as historical eve
 ## How does Personas handle identity merging?
 Each incoming event is analyzed and external IDs are extracted (`user_id`, `anonymous_id`, `email`). The simplified algorithm works as follows:
 
-- We first search the Identity Graph for incoming external IDs.
-- If we find no users, we'll create one.
+- Segment first searches the Identity Graph for incoming external IDs.
+- If Segment find no users, it creates one.
 - If one user is returned, then that user is chosen.
-- If multiple users are returned, our merge protection kicks in and checks the validity of all of the provided external IDs.
-  - If the merge protection checks pass, we'll create a new merge connection between those two users. The first user profile ever created becomes the parent profile, and all merged users become child profiles.
-  - If the merge protection checks fail, we'll discard the lowest precedence external ID and re-run the algorithm.
+- If multiple users are returned, merge protection kicks in and checks the validity of all of the provided external IDs.
+  - If the merge protection checks pass, Segment creates a new merge connection between those two users. The first user profile ever created becomes the parent profile, and all merged users become child profiles.
+  - If the merge protection checks fail, Segment discards the lowest precedence external ID and re-run the algorithm.
 
-![](images/merging_1.png)
+![Identity graph merging](images/merging_1.png "Flowchart of Segment receiving an incoming event")
 
-![](images/merging_2.png)
+![Identity graph merging](images/merging_2.png "Flowchart of Segment searching for profiles by external ID")
 
-![](images/merging_3.png)
+![Identity graph merging](images/merging_3.png "Flowchart of Segment merging profiles")
 
 ## Is all matching deterministic, or is there any support for probabilistic matching?
 All Profile matching is deterministic and based on first-party data that you've collected.
 
-We do not support probabilistic matching. We've found that most marketing automation use cases require 100% confidence that a user is who you think they are (sending an email, delivering a recommendation, etc). We've found the best way to support this is through a deterministic identity algorithm.
+Segment doesn't support probabilistic matching. Most marketing automation use cases require 100% confidence that a user is who you think they are (sending an email, delivering a recommendation, and so on). The best way to support this is through a deterministic identity algorithm.
 
 ## Should I use Personas if I already have a marketing automation tool?
 Personas pairs well with marketing automation tools on the Segment platform.
@@ -95,7 +98,7 @@ From there, your marketing, product, sales, and success teams have channels on w
 
 They can contact you using livechat, email, push notification, or text. Success can better prioritize their support ticket in Zendesk, or hone in on the customer's problem faster. On the sales side, they can focus on the products a prospect is most engaged with, or focus on getting the customer on the right plan. Your product team can serve specific recommendations, based on that user's specific needs next time they visit your site.
 
-Today, most businesses are forced to think about each channel as individual siloes. With Personas, all channels — including your marketing automation tool — can be powered by the same, singular understanding of your users.
+Today, most businesses are forced to think about each channel as individual silos. With Personas, all channels — including your marketing automation tool — can be powered by the same, singular understanding of your users.
 
 ## What are Funnel Audiences?
 Funnel Audiences allow you to use **strict, relative ordering** for your audience conditions. Common use cases for these audiences are Cart Abandonment (users that triggered the Product Added event but did not trigger the Order Completed event after the Product Added event occurred) and onboarding steps (users that Added Credit Card but did not Subscribe afterward).
@@ -108,32 +111,33 @@ The funnel condition will now be relative to the parent condition.
 
 The audience in the image below includes all users that have Product Added in the last week, but not Order Completed within a day of doing so.
 
-![](images/funnel_audience.png)
+![Funnel condition](images/funnel_audience.png "A screenshot of using funnel conditions in the Personas Audience builder")
 
 **Important:** Funnel Audiences compute based on all instances of the parent event within the lookback period. This means that if you have a user that Product Added ⟶ Order Completed ⟶ Product Added, this user would be entered into the Abandoned Cart state despite having previously completed an order.
 
 ## What happens to conflicting and non-conflicting profile attributes?
-If two merged user profiles contain conflicting profile attributes, we'll select the newest, or last updated, attributes when querying the profile. In the future, we'll let the conflict resolution policies be configurable.
+If two merged user profiles contain conflicting profile attributes, Segment selects the newest, or last updated, attributes when querying the profile.
 
 ## What is Personas Merge Protection?
 Personas merge protection algorithm protects your identity graph from unnecessary merges by finding and removing untrusted external IDs. Here's an example:
 
-![](images/merge_protection.png)
+![Merge protection](images/merge_protection.png "An image representing the merge protection flow")
 
-In this example, `anonymous_id: a1` is not reset during a `User Logout`. Without merge protection, we'd merge `user_id u1` and `user_id u2`. Instead, our Merge Protection algorithm detects that such a merge would break user_id uniqueness and prevents the merge.
+In this example, `anonymous_id: a1` is not reset during a `User Logout`. Without merge protection, Segment would merge `user_id u1` and `user_id u2`. Instead, the Merge Protection algorithm detects that such a merge would break user_id uniqueness and prevents the merge.
 
 This is especially helpful for preventing "blob users" that are merged together by non-unique anonymous IDs or by common group emails like `[email protected]`.
 
 ## Which destinations support syncing the identity graph?
 Most destinations on the Segment Platform are built up around a user model. They assume that a user will have a single userId. Further, most Destinations are not built to handle anonymous traffic.
 
-By default, we do not sync the output of the Identity Graph to Destinations. However, Segment computed traits and audiences are based on the entire user profile, including anonymous and merged data. We sync the value of these computations (e.g. `blog_posts_ready_30_days: 10`) using all `userIds` on the profile.
+By default, Segment doesn't sync the output of the Identity Graph to Destinations. However, Segment computed traits and audiences are based on the entire user profile, including anonymous and merged data. We sync the value of these computations (e.g. `blog_posts_ready_30_days: 10`) using all `userIds` on the profile.
 
-For Destinations that support an `alias` call (for example, Mixpanel), we have the option to emit an alias call on merge.
+For Destinations that support an `alias` call (for example, Mixpanel), you can emit an `alias` call on merge.
 
 ## What Sources can I sync to Personas?
 
-You can sync data from your…
+The following list shows just some data sources you can sync to Personas:
+
 - Website ([analytics.js](/docs/connections/sources/catalog/libraries/website/javascript/))
 - Mobile SDKs ([ios](/docs/connections/sources/catalog/libraries/mobile/ios), [android](/docs/connections/sources/catalog/libraries/mobile/android), [amp](/docs/connections/sources/catalog/libraries/mobile/amp))
 - Serverside libraries ([go](/docs/connections/sources/catalog/libraries/server/go), [node](/docs/connections/sources/catalog/libraries/server/node/), [java](/docs/connections/sources/catalog/libraries/server/java), [PHP](/docs/connections/sources/catalog/libraries/server/php/), [python](/docs/connections/sources/catalog/libraries/server/python), [ruby](/docs/connections/sources/catalog/libraries/server/ruby), [.NET](/docs/connections/sources/catalog/libraries/server/net))
@@ -157,11 +161,11 @@ You can sync data from your…
 
 ## Can I send audiences to multiple destination accounts?
 
-Yes, Personas now supports the ability to send an audience or computed trait to two or more accounts of the same partner. The most common use case is multiple Facebook, or Adwords ad accounts.
+Yes, Personas supports the ability to send an audience or computed trait to two or more accounts of the same partner. The most common use case is multiple Facebook, or Adwords ad accounts.
 
-![](images/multi-facebook.png)
+![Multiple Destination sends](images/multi-facebook.png "Sending Personas audience traits to two Facebook accounts")
 
 
 ### What identifiers can the merged profile be queried/updated with?
 
-Any of the external IDs can be used to query a profile. When a profile is requested, we will traverse the merge graph and resolve all merged profiles. The result is a single profile, with the latest state of all traits, events, and identifiers.
+Any of the external IDs can be used to query a profile. When a profile is requested, Segment traverses the merge graph and resolves all merged profiles. The result is a single profile, with the latest state of all traits, events, and identifiers.