Merge pull request #10 from segmentio/repo-sync

repo sync

Author: bot-docsteam

src/connections/destinations/catalog/customer-io/images/segment-destination-cio.png

@@ -5,9 +5,7 @@ redirect_from: "/connections/destinations/catalog/customer.io/"
 hide-personas-partial: true
 ---
 
-[Customer.io](https://customer.io/) lets you send automated email, push, SMS, letters, and webhooks based on your customer's activities in your app or product. It makes conversion tracking, optimization and remarketing easier. The `analytics.js` Customer.io Destination is open-source. You can browse the code [on GitHub](https://github.com/segment-integrations/analytics.js-integration-customerio).
-
-This document was last updated on January 26, 2018. If you notice any gaps, out-dated information or want to leave some feedback to help improve the documentation, [let us know](https://segment.com/help/contact)!
+[Customer.io](https://customer.io/) helps you send automated email, push, SMS, and webhooks based on your customers' activities in your app or product. It makes conversion tracking, optimization and re-marketing easier. The `analytics.js` Customer.io Destination is open-source. You can browse the code [on GitHub](https://github.com/segment-integrations/analytics.js-integration-customerio).
 
 > success ""
 > **Good to know**: This page is about the Customer.io Segment destination, which receives data from Segment. There's also a page about the [Customer.io Segment source](/docs/connections/sources/catalog/cloud-apps/customer-io/), which sends data _to_ Segment!
@@ -17,23 +15,15 @@ This document was last updated on January 26, 2018. If you notice any gaps, out-
 
 {% include content/connection-modes.md %}
 
-To connect Customer.io as a Segment destination:
-1. Navigate to **Connections > Destinations** in Segment.
-2. Click **Add Destination**.
-3. Search for `Customer.io` and select it.
-4. Click **Configure Customer.io** and choose which source to connect the destination to.
-5. Enter your settings for these fields and click **Save**:
-
-    Field | Details
-    ----- | -------
-    Destination Name | The name you want to identify the destination with.
-    Connection Mode | You can choose between **Cloud Mode** and **Device Mode**. Segment recommends using Cloud Mode.
-    How would you like to set up this destination? | You can choose to fill the settings manually or copy the settings from an existing destination instance.
+You can follow the setup guide through Segment using the steps below, or you can automatically sync your Customer.io connection settings to your Segment source using the flow in your Customer.io workspace’s Integrations page.
 
-6. Enter your **API Key** and **Site ID** on the Settings tab of your new destination. You can find these in your Customer.io account under **Account Settings > API Credentials**.
-7. Click the toggle to activate the integration and start sending data to your Customer.io destination.
+1. From the Segment web app, click **Connections** > **Destinations**.
+1. Search for “Customer.io”, select it, and then click **Configure Customer.io**.
+1. Select the data sources you want to connect to Customer.io and click **Next**.
+1. Enter your *Destination Name* and select your **Connection Mode**—Cloud Mode or Device Mode. Click **Save**.
+1. Under *Connection Settings*, enter your Customer.io workspace **API Key** and **Site ID**. You’ll find both in your Customer.io *Account Settings* > *API Credentials* page.
 
-If you want to sync your settings directly from your Customer.io workspace instead, go to **Settings > Integrations** and find the **Segment Destination** integration. .
+If you want to sync your settings directly from your Customer.io workspace, go to **Settings** > **Integrations** and find the **Segment Destination** integration. 
 
 ![Segment Destination in Customer.io](images/segment-destination-cio.png)
 
@@ -60,19 +50,47 @@ Screen events send to Customer.io as a custom event. In the Customer.io "Activit
 
 ## Identify
 
-If you're not familiar with the Segment Specs, take a look to understand what the [Identify method](/docs/connections/spec/identify/) does. An example call would look like:
+If you're not familiar with the Segment Specs, take a look to understand what the [Identify method](/docs/connections/spec/identify/) does. An example call looks like this:
 
 ```javascript
 analytics.identify('userId123', {
   email: '[email protected]'
 });
 ```
 
-An email address isn't required by Customer.io. It's only needed for people you intend to send email messages to (as opposed to SMS or push notifications). If you want an email to appear in the Customer.io "People View", you must provide an email as a trait labeled `email`.
+When you identify a new user, Customer.io adds the user to your Customer.io workspace. If the user exists, the identify request updates the existing person’s attributes.
+
+If your Customer.io workspace supports both `email` and `id` as identifiers (the default setting as of June 2021), you can identify people either by a database identifier (called `id` in Customer.io) or the `email` trait.
+
+This provides a path to identify people who enter your system as leads (by email) and then assign them an ID in Customer.io when they become a customer or user.
+
+* If you don't have an ID, pass a person's email address as the `userId` in the identify call. Customer.io maps this value to a person's `email` attribute.
+* If you have an ID, set the `userId` in the identify call to the person's ID and pass `email` as a trait. This sets both a person's `id` and `email` attributes in Customer.io. If you previously identified a person by `email`, your request updates that person and assigns them an `id`.
+
+
+### Updating people
+
+When Customer.io recognizes either the `id` or `email` in your request, your identify request updates that person.
+
+```javascript
+analytics.identify('userId123', {
+  email: '[email protected]',
+  fav_food: ‘pizza’
+});
+```
+
+If you want to change the `id` or `email` you've assigned a person in Customer.io, you have to pass a person's `cio_id`, in the format `cio_<cio_id value>` as the `userId` in your identify call. Currently, you must retrieve this value from a person's page in the Customer.io interface. In the future, you'll be able to do that using this call from Customer.io API.
+
+```javascript
+analytics.identify('cio_<cio_id value>', {
+  email: '[email protected]',
+  id: 'new-id-value'
+});
+```
 
-When you identify a new user, the user will subscribe to Customer.io. If the user is already subscribed, the user attributes will update according to the traits provided.
+### Unsubscribing Users
 
-To unsubscribe a user, pass in `user_id` and `unsubscribed` (with a value of true) in an `identify` call. Be sure the `user_id` and `email` match the values in Customer.io, which you can find in the "Overview" section under the "Attributes" column within an individual user's view in the Customer.io UI. Here is an example of how to unsubscribe a user:
+To unsubscribe a user, simply pass `unsubscribed: true` in an identify call. Be sure the `id` and/or `email` values match the values in Customer.io. You can find these values in Customer.io by selecting a person on the _People_ page, and clicking _Attributes_. Here is an example that unsubscribes a user:
 
 ```javascript
 analytics.identify('userId123', {
@@ -81,6 +99,13 @@ analytics.identify('userId123', {
   }
 )
 ```
+
+### Identifying people in workspaces that only support ID
+
+In older workspaces, or workspaces using Customer.io's "classic" settings, you can only identify people by ID.
+
+You do not need to pass an email address unless you want to send emails. If you want to send emails, you must provide the email address as a trait labeled `email`.
+
 ## Track
 
 If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/connections/spec/track/) does. An example call would look like:
@@ -140,7 +165,8 @@ For that, you need to make the following calls:
 }
 ```
 
- ## Application Opened
+## Application Opened
+
 [Application Opened](/docs/connections/spec/mobile/#application-opened) events will add or update a device in the person's Customer.io profile using the same endpoint as above.  If a device already exists, Customer.io will update its `last_used_at` timestamp. Again, make sure you pass a device token in your event payload using a `context.device.token` property. See more on [Contextual properties](/docs/connections/spec/common/#context).
 
 {% comment %} api-example '{
@@ -177,7 +203,8 @@ For that, you need to make the following calls:
 }
 ```
 
- ## Application Uninstalled
+## Application Uninstalled
+
 [Application Uninstalled](/docs/connections/spec/mobile/#application-installed) events will remove the device from the person's Customer.io profile using [this](https://customer.io/docs/api/#apitrackcustomersdevices_delete) API endpoint. Note, you must pass a device token in your event payload using a `context.device.token` property. See more on [Contextual properties](/docs/connections/spec/common/#context).
 
 
@@ -217,12 +244,15 @@ For that, you need to make the following calls:
 
 ### Sending Data from Customer.io
 
-Customer.io supports sending [email events](/docs/connections/spec/email/) to other tools on the Segment platform. These events send as `track` calls to the other destinations you've turned on.
+You can enable Customer.io as a Segment Source to send[ email events](/docs/connections/spec/email/) to other tools on the Segment platform. These events are sent as track calls to the other destinations you’ve turned on.
 
-To enable this feature, go to the Account Settings in Customer.io and add your Segment write key:
+To enable this feature: 
 
-![Send email events from Customer.io](images/customerio_streaming_data_out.png)
+1. In Customer.io go to **Settings** > **Integrations**.
+2. Find the Segment Source integration. 
+3. Add your _Segment Write Key_ and click **Connect Segment**.
 
+![Segment source in Customer.io](images/segment-source-cio.png)
 
 ## Best Practices
 
@@ -245,6 +275,6 @@ You can send computed traits and audiences generated using [Segment Personas](/d
 For user-property destinations, an [identify](/docs/connections/spec/identify/) call sends to the destination for each user that's added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Personas sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Personas sets that value to `false`.
 
 > note ""
-> Customer.io requires you to pass a `userId` value when you sync Audiences or Computed Traits.
+> Customer.io requires you to pass an identifier value (ID or email, depending on your workspace settings), when you sync Audiences or Computed Traits.
 
 When you first create an audience, Personas sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.