diff --git a/src/connections/destinations/catalog/correlated/index.md b/src/connections/destinations/catalog/correlated/index.md index 438c1c4fdf..8602d739f0 100644 --- a/src/connections/destinations/catalog/correlated/index.md +++ b/src/connections/destinations/catalog/correlated/index.md @@ -3,30 +3,30 @@ title: Correlated Destination id: 60df6d4c038b872f10c54801 --- -[Correlated](https://www.getcorrelated.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_new"} is the first product-led revenue platform built to help you and your sales teams take action based on how customers are using your product. +[Correlated](https://www.getcorrelated.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank"} is the first product-led revenue platform built to help you and your sales teams take action based on how customers are using your product. -This destination is maintained by Correlated. For any issues with the destination, [contact the Correlated Support team](mailto:support@getcorrelated.com). +This destination is maintained by Correlated. For any issues with the destination, [contact the Correlated support team](mailto:support@getcorrelated.com){:target="_blank"}. > success "" -> Set up a free account with Correlated by visiting their [website](https://docs.getcorrelated.com/docs/setting-up-your-account){:target="_new"}. +> To set up a free account with Correlated, visit their [website](https://docs.getcorrelated.com/docs/setting-up-your-account){:target="_blank"}. -## Getting Started +## Getting started ### Connect with OAuth 1. Log in to the Correlated application. 2. Go to [Correlated integrations](https://app.getcorrelated.com/integrations){:target="_blank"} and select the Segment integration. 3. Click **Connect to Segment** to connect with OAuth. -4. Select the relevant Sources that you want to include (Correlated recommends that you include your website and application) +4. Select the relevant sources that you want to include. Correlated recommends that you include your website and application. ### Connect with an API Key 1. From the Destinations catalog page in the Segment App, click **Add Destination**. 2. Search for "Correlated" in the Destinations Catalog, and select the "Correlated" destination. -3. Choose which Source should send data to the "Correlated" destination. +3. Choose which source should send data to the "Correlated" destination. 4. Go to [Correlated integrations](https://app.getcorrelated.com/integrations){:target="_blank"} and click on the "Segment" integration. 5. Copy the "Segment API key". -6. Enter the "Segment API Key" in the "Correlated" destination settings in Segment. +6. Enter the Segment API key in the "Correlated" destination settings in Segment. -## Supported Methods +## Supported methods Correlated supports the following methods. @@ -76,4 +76,4 @@ If you aren't familiar with the Segment Spec, take a look at the [Track method d analytics.track('Login Button Clicked') ``` -Segment sends Track calls to Correlated as a `track` event. Track events should be flattened whenever possible. For example, rather than "Button Click" as a track event with "Onboarding Form Submit" as a property, use "Onboarding Form Submit Button Click". `Product Events` can be filtered and grouped by identify traits or group traits. \ No newline at end of file +Segment sends Track calls to Correlated as a `track` event. Track events should be flattened whenever possible. For example, rather than "Button Click" as a track event with "Onboarding Form Submit" as a property, use "Onboarding Form Submit Button Click". `Product Events` can be filtered and grouped by identify traits or group traits. diff --git a/src/connections/destinations/catalog/marketo-v2/index.md b/src/connections/destinations/catalog/marketo-v2/index.md index 635c934faa..a0f00ff605 100644 --- a/src/connections/destinations/catalog/marketo-v2/index.md +++ b/src/connections/destinations/catalog/marketo-v2/index.md @@ -1,81 +1,75 @@ --- -title: Marketo V2 Destination +title: Marketo v2 Destination strat: adobe id: 58f8f55a70a3e552b955a444 --- -## Getting Started +## Getting started To start sending data to Marketo, there are two things you must do. **Both of these steps require that you to log in with the Admin Marketo Account.** -### Enter your Marketo Credentials into your Destination settings -We'll need your Munchkin Account ID, Client Secret, and Client ID. - -To get your Munchkin Account ID [login to your Marketo account](https://login.marketo.com/){:target="_blank"}, click Admin in the top right corner, then click Munchkin on the left side bar. +### 1. Enter your Marketo Credentials into your Destination settings +You need to enter your Munchkin Account ID, Client Secret, and Client ID. +To get your Munchkin Account ID, [login to your Marketo account](https://login.marketo.com/){:target="_blank"}, click **Admin**, then **Munchkin** in the side bar. ![A screenshot of a Marketo account.](images/iL42ERv0g5X+.png) - To get your Client Secret and Client ID, you must create a role that has full API access, an API only user, and then create a Service in Marketo. To create a role with full API access: -1. Click **Admin** in the top right corner. -2. Click **Users & Roles** on the left side bar. +1. Click **Admin**. +2. Click **Users & Roles** in the side bar. 3. Click on the **Roles** tab. -4. Click **New Role**. Name your role and check the API Access box to assign the user full API access. Click Create. -![A screenshot of the Create New Role popup in Marketo.](images/cV2x9pHb44g+.png) - +4. Click **New Role**. Name your role and check the API Access box to assign the user full API access. Click **Create**. +![A screenshot of the Create New Role popup in Marketo.](images/cv2x9pHb44g+.png) -Now that you've created an API role, you have to assign that role to an API only user. +Once you've created an API role, you have to assign that role to an API only user. -1. Click the Users tab. -2. Click Invite New User and fill out the necessary information in Step 1. -3. Assign the new role you created to this user in Step 2 and check the API Only box. Click next then Send. +1. Click the **Users** tab. +2. Click **Invite New User** and fill out the necessary information in Step 1. +3. Assign the new role you created to this user in Step 2 and check the API Only box. Click **Next**, then **Send**. ![A screenshot of the Invite New User popup in Marketo.](images/cJkQ9XD6FsE+.png) - Next, create a Service and get Client Secret and Client ID from that Service. -1. Click LaunchPoint on the left side bar. -2. Click New and then New Service from the drop down. -3. Select Custom for the Service from the drop down. -4. Select the new API Only user you invited. This User must be an API Only user **and** be assigned a role that has full API access. +1. Click **LaunchPoint** in the side bar. +2. Click **New > New Service**. +3. Select **Custom for the Service**. +4. Select the new API-Only user you invited. This user must be an API_Only user **and** be assigned a role that has full API access. ![A screenshot of the New Service popup in Marketo.](images/cWwQBeVFto0+.png) -1. Click View Details on the new service that you've created and a small window will display with your Client Secret and Client ID. Copy and paste them into your Destination's Settings. +1. Click **View Details** on the new service that you've created. Your Client Secret and Client ID are displayed in a small window. Copy and paste them into your destination's settings. ![A screenshot of the Marketo Installed Services tab.](images/c3s0qJ-dDSO+.png) +### 2. Create a User ID and an Anonymous ID field in Marketo -### Create a User ID and an Anonymous ID field in Marketo - -1. Click Admin in the top right corner. -2. Click Field Management on the left side bar. -3. Click New Custom Field. -4. Select String as the type. +1. Click **Admin**. +2. Click **Field Management** in the side bar. +3. Click **New Custom Field**. +4. Select **String** as the type. 5. Name the field whatever you'd like. -6. Set the API name to `userId` for the user ID field and then `anonymousId` for the anonymous ID field. **Important:** The API names for the user ID and anonymous ID fields must be `userId` and `anonymousId` exactly. If anything in the API name is different, the destination will not work. +6. Set the API name to `userId` for the user ID field and then `anonymousId` for the anonymous ID field. **Note**: The API names for the user ID and anonymous ID fields must be `userId` and `anonymousId` exactly. If anything in the API name is different, the destination won't work. ![An animation showing someone do the above steps to create User ID and Anonymous ID fields.](images/kzayYEY2JL.gif) ----------- ## Identify ### Cloud-mode -When you call [`Identify`](/docs/connections/spec/identify/) in Cloud-mode, Segment uses [Marketo's REST API](http://developers.marketo.com/rest-api/lead-database/leads/#create_and_update){:target="_blank"} to create and update leads server-side. +When you call [Identify](/docs/connections/spec/identify/) in Cloud-mode, Segment uses [Marketo's REST API](http://developers.marketo.com/rest-api/lead-database/leads/#create_and_update){:target="_blank"} to create and update leads server-side. ### Device-mode -When you call [`Identify`](/docs/connections/spec/identify/) in Device-mode, Segment uses [Marketo's Background Form Submission](https://developers.marketo.com/blog/make-a-marketo-form-submission-in-the-background/){:target="_blank"} to create and update leads client-side. +When you call [Identify](/docs/connections/spec/identify/) in Device-mode, Segment uses [Marketo's Background Form Submission](https://developers.marketo.com/blog/make-a-marketo-form-submission-in-the-background/){:target="_blank"} to create and update leads client-side. -There are additional steps you must take to send `.identify()` calls in Device-mode. +There are additional steps you must take to send Identify calls in Device-mode. 1. Create an empty form in Marketo. This form will always be hidden and can remain empty as long as the traits you need downstream are mapped in the **Marketo Custom Fields** Destination setting. -2. Input the associated **Marketo Form ID** and **Marketo Form URL** in your Marketo V2 Destination settings. This information can be found in Form Actions > Embed Code in the Marketo Design Studio: +2. Input the associated **Marketo Form ID** and **Marketo Form URL** in your Marketo v2 Destination settings. This information can be found in **Form Actions > Embed Code** in the Marketo Design Studio: ![A screenshot of the Embed Code popup in Marketo.](images/form-info.png) > info "" -> **Marketo Form ID** and **Marketo Form URL** are **required** fields for the Marketo SDK to initialize on your site. If these fields are left blank, the SDK will not initialize and data will not be sent downstream. +> **Marketo Form ID** and **Marketo Form URL** are **required** fields for the Marketo SDK to initialize on your site. If these fields are left blank, the SDK won't initialize and data won't be sent downstream. ### Traits -Regardless of connection mode, we'll map the following spec'd Segment traits to Marketo's standard fields: +Regardless of connection mode, following spec'd Segment traits are mapped to Marketo's standard fields: | **Segment Traits** | **Marketo Standard Fields** | | --------------------- | --------------------------- | @@ -112,22 +106,22 @@ analytics.identify('1234', { }); ``` -If you'd like any other traits from your `.identify()` call to update a field in Marketo, you must create custom fields in Marketo and map them in the **Marketo Custom Fields** Destination setting. +If you'd like any other traits from your Identify call to update a field in Marketo, you must create custom fields in Marketo and map them in the **Marketo Custom Fields** Destination setting. ![A screenshot of the Marketo Settings page in Segment.](images/c1X7nf6wDIX+.png) -- **Segment Trait**. The name of the trait sent in your `.identify()` call. -- **Marketo Field Name**. The Marketo REST API name for the field. To get the REST API name for your fields in Marketo, click Field Management, then Export Field Names. A spreadsheet will download and the first column is the REST API name for your Marketo fields. **Make sure to copy and paste the REST API name exactly. This is case sensitive.** -- **Marketo Field Type**. When you are in Field Management, click on the field name in the bar on the right and you'll see the field type. +- **Segment trait**: The name of the trait sent in your Identify call. +- **Marketo field name**: The Marketo REST API name for the field. To get the REST API name for your fields in Marketo, click **Field Management**, then **Export Field Names**. A spreadsheet downloads and the first column is the REST API name for your Marketo fields. **Make sure to copy and paste the REST API name exactly. This is case sensitive.** +- **Marketo field type**: When you are in Field Management, click on the field name to see the field type. ![A screenshot of the Marketo Field Management tab.](images/cubJQKkGLfF+.png) -**Note:** Custom `address` traits must go in the top level `traits` object, not in the `address` object. +**Note**: Custom `address` traits must go in the top level `traits` object, not in the `address` object. ## Track -When you call [`Track`](/docs/connections/spec/track/), Segment maps the event to a pre-defined [Marketo Custom Activity](http://docs.marketo.com/display/public/DOCS/Understanding+Custom+Activities){:target="_blank"}. There are two important things to note when sending `.track()` calls to Marketo: +When you call [Track](/docs/connections/spec/track/), Segment maps the event to a pre-defined [Marketo Custom Activity](http://docs.marketo.com/display/public/DOCS/Understanding+Custom+Activities){:target="_blank"}. There are two important things to note when sending Track calls to Marketo: -1. You **must** map them to your Marketo Custom Activities in your Destination Settings. If you do not map a track call to a Custom Activity in your Destination Settings, we will not send the event to Marketo to help limit the amount of API calls made to Marketo. +1. You **must** map them to your Marketo Custom Activities in your Destination Settings. If you don't map a track call to a Custom Activity in your destination settings, the event won't be sent to Marketo to help limit the amount of API calls made to Marketo. 2. You must either: @@ -135,7 +129,7 @@ When you call [`Track`](/docs/connections/spec/track/), Segment maps the event t - Enable [Device-mode](/docs/connections/destinations/catalog/marketo-v2/#supported-sources-and-connection-modes) and enable the [Send Track Events Server Side](/docs/connections/destinations/catalog/marketo-v2/#send-track-events-server-side) setting - Send track events from one of our [server side libraries](/docs/connections/sources/#server) -Here is a sample Ruby `.track()` event: +Here is a sample Ruby Track event: ```js Analytics.track( @@ -148,30 +142,30 @@ Analytics.track( ![A screenshot of the Destination Settings page in Segment for the Marketo v2 Destination.](images/c2l53wGTCVP+.png) -- **Segment Event Name**. Your Segment Event name. -- **Marketo Activity ID**. When you are in [Marketo Custom Activities](http://docs.marketo.com/display/public/DOCS/Understanding+Custom+Activities){:target="_blank"}, click on the Marketo Activity in the right side bar that you'd like to map your Segment Track event to. Copy and paste the ID into your Destination Settings. +- **Segment event name**: Your Segment Event name. +- **Marketo activity ID**: When you are in [Marketo Custom Activities](http://docs.marketo.com/display/public/DOCS/Understanding+Custom+Activities){:target="_blank"}, click on the Marketo Activity in the right side bar that you'd like to map your Segment Track event to. Copy and paste the ID into your Destination Settings. ![A screenshot of the Marketo Custom Activities page.](images/cwZqHwQfs3M+.png) -- **Segment Property Name**. The name of the property in your `.track()` call. This is case sensitive so make sure the name matches exactly how you are passing it in your `.track()` call. -- **Marketo Field Name**. The name of the Marketo Attribute for your Custom Activity. The Attribute names for a given Custom Activity can be found in the Fields tab of Marketo Custom Attributes. Click on the Custom Activity in the right side bar and a list of your Attributes for that Custom Activity will appear. **Make sure to copy and paste the API Name for your field exactly as it appears in Marketo. This is case sensitive.** +- **Segment property name**: The name of the property in your Track call. This is case sensitive so make sure the name matches exactly how you are passing it in your Track call. +- **Marketo field name**: The name of the Marketo attribute for your Custom Activity. The attribute names for a given Custom Activity can be found in the **Fields** tab of **Marketo Custom Attributes**. Click on **Custom Activity** to see a list of your attributes for that Custom Activity. **Make sure to copy and paste the API Name for your field exactly as it appears in Marketo. This is case sensitive.** ![A screenshot of the Fields tab inside of the Marketo Custom Activities page.](images/cNSP-7ryT72+.png) -- **Marketo Field Type**. The type of the Marketo Attribute. The Attribute type can be found in the Fields tab of Marketo Custom Attributes. Click on the Custom Activity in the right side bar and a list of your Attributes for that Custom Activity will appear. +- **Marketo field type**: The type of the Marketo attribute. The attribute type can be found in the **Fields** tab of **Marketo Custom Attributes**. Click on **Custom Activity** to see a list of your attributes for that Custom Activity. ![A screenshot of the Fields tab inside of the Marketo Custom Activities page.](images/cIBsfYeh2B8+.png) -- **Primary Field**. When creating a Custom Activity in Marketo, you have to set a Primary Field. If you are unsure which field was set as the primary field, when you are looking at the list of fields for your Custom Activity in Marketo, there will be a red star next to your Primary Field. +- **Primary field**. When creating a Custom Activity in Marketo, you have to set a Primary Field. If you are unsure which field was set as the primary field, when you are looking at the list of fields for your Custom Activity in Marketo, primary fields are denoted by a red star. ![A screenshot of the Fields tab inside of the Marketo Custom Activities page.](images/cZuvsHeaepX+.png) > info "" -> You can't map fields nested in objects as Marketo Custom Activity property names. You must flatten any objects you may need to access data from either before you send it to Segment, or while using an [Insert Function](/docs/connections/functions/insert-functions/). +> You can't map fields nested in objects as Marketo Custom Activity property names. You must flatten any objects you may need to access data from either before you send it to Segment, or while using an [Insert function](/docs/connections/functions/insert-functions/). ## Page -When you call [`Page`](/docs/connections/spec/page/), Segment uses [Marketo's Munchkin.js `visitWebPage` method](http://developers.marketo.com/javascript-api/lead-tracking/api-reference/#munchkin_visitwebpage){:target="_blank"}. The URL is built from your `.page()` event and properties object into the form Marketo expects, so no need to worry about doing that yourself. +When you call [Page](/docs/connections/spec/page/), Segment uses [Marketo's Munchkin.js `visitWebPage` method](http://developers.marketo.com/javascript-api/lead-tracking/api-reference/#munchkin_visitwebpage){:target="_blank"}. The URL is built from your Page event and properties object into the form Marketo expects, so no need to worry about doing that yourself. -Marketo's `visitWebPage` method requires a URL and a user agent. Any calls that are missing either of these fields will not be sent to Marketo. User agent is automatically collected Client-side but if you are sending `.page()` calls from the server, make sure to set the user agent. +Marketo's `visitWebPage` method requires a URL and a user agent. Any calls that are missing either of these fields aren't sent to Marketo. User agent is automatically collected client-side but if you are sending Page calls from the server, make sure to set the user agent. -Here is a sample Node `.page()` event: +Here is a sample Node Page event: ```js analytics.page({ @@ -191,20 +185,25 @@ Here is a sample Node `.page()` event: ``` -## Tracking Anonymous Activity in Marketo +## Tracking anonymous activity in Marketo -If you would only like to track known users in Marketo, set your Track Anonymous Activity setting to false. There are a couple things to note when this setting is false: +If you'd only like to track known users in Marketo, set your Track Anonymous Activity setting to `false`. There are some things to note when this setting is false: -1. Any call without a User ID will be rejected. -2. No anonymous activity will be sent to Marketo. Even after the user becomes known, none of their previous anonymous activity will be sent to Marketo. +1. Calls without a User ID are rejected. +2. No anonymous activity is sent to Marketo. Even after the user becomes known, none of their previous anonymous activity will be sent to Marketo. -If you'd like to track anonymous activity but don't want to have to parse through or view unknown leads, Marketo lets you create Smart Lists that will filter your leads (i.e. if you'd only like to view leads that have a user ID or an email). To do this, when you are in your Lead Database, click All Leads, then New. From the drop down, click New Smart List. Select the folder you'd like the Smart List to live in. After you've created the Smart List, select what field you'd like to filter by on the right side bar, drag it to the filters and then select what you'd specifically like to filter by for that field. +If you'd like to track anonymous activity but don't want to have to parse through or view unknown leads, Marketo lets you create Smart Lists that filter your leads. For example, you can filter to only view leads that have a user ID or an email. To do this, when you are in your Lead Database: + +1. Click **All Leads**, then **New**. +2. From the drop down, click **New Smart List**. +3. Select the folder you'd like the Smart List to live in. +4. After you've created the Smart List, select what field you'd like to filter by, drag it to the filters and then select what you'd specifically like to filter by for that field. ![An animation showing a Smart List being created.](images/5bxmcClCgU.gif) -## Marketo API Limits +## Marketo API limits -We do our best to limit the amount of API calls that we are making to Marketo but if you are hitting your 50k/day limit, we'd recommend only sending events to Marketo that you need. To prevent an event from being sent to Marketo, you can select destinations by doing the following: +Segment tries to limit the amount of API calls being made to Marketo but if you are hitting the 50 k/day limit, Segment recommends only sending events to Marketo that you need. To prevent an event from being sent to Marketo, you can select destinations by doing the following: ```js analytics.identify({ @@ -213,68 +212,74 @@ We do our best to limit the amount of API calls that we are making to Marketo bu firstName: 'Alex' }, integrations: { - 'Marketo V2': false, + 'Marketo v2': false, 'Google Analytics': true } }) ``` -## Hybrid Device/Cloud-mode -Another option is to use Marketo in [Device-mode](/docs/connections/destinations/catalog/marketo-v2/#supported-sources-and-connection-modes) (assuming you are tracking events from a Website). Marketo does not limit API calls that originate from their Web SDK but it also only supports capturing Identify and Page events. If you would also like to capture Track events, you can choose to have these be routed through our server-side integration. +## Hybrid device or cloud-mode +Another option is to use Marketo in [device-mode](/docs/connections/destinations/catalog/marketo-v2/#supported-sources-and-connection-modes) (assuming you are tracking events from a website). Marketo does not limit API calls that originate from its web SDK, but it only supports capturing Identify and Page events. If you'd also like to capture Track events, you can choose to have these be routed through Segment's server-side integration. -To enable this "Hybrid" mode, select the [Send Track Events Server Side](/docs/connections/destinations/catalog/marketo-v2/#send-track-events-server-side) setting and follow the instructions for mapping [Track](/docs/connections/destinations/catalog/marketo-v2/#track) events defined above. +To enable this "Hybrid" mode, select the **[Send Track Events Server Side](/docs/connections/destinations/catalog/marketo-v2/#send-track-events-server-side)** setting and follow the instructions for mapping [Track](/docs/connections/destinations/catalog/marketo-v2/#track) events. ## Preventing Duplicate Leads -Marketo allows you to upsert leads based on any field. We use email and userId as well as anonymousId if you are tracking anonymous activity. We will first use email since that is the field Marketo recommends is unique for your leads. However, many `.track()` and `.page()` calls don't include an email address so then we will use the `userId` or `anonymousId` passed in your `.track()` and `.page()` calls to associate these events to leads in Marketo. +Marketo allows you to upsert leads based on any field. Segment uses `email` and `userId`, as well as `anonymousId` if you are tracking anonymous activity. `email` is used first since that is the field Marketo recommends is unique for your leads. However, many Track and Page calls don't include an email address. In that case, Segment uses the `userId` or `anonymousId` passed in your Track and Page calls to associate these events to leads in Marketo. You can do one of the following to prevent duplicate leads: +**Recommended: Upload a CSV adding your userId to all your leads in Marketo _before_ enabling the destination**. -1. **Recommended:** Upload a CSV adding your userId to all your leads in Marketo **before** enabling the destination. After you [create the userId field](/docs/connections/destinations/catalog/marketo-v2/#2-you-must-create-a-user-id-and-an-anonymous-id-field-in-marketo) in Marketo, you can upload a list of all your users with an email column and a userId column. Your CSV should look like this: +After you [create the `userId` field](/docs/connections/destinations/catalog/marketo-v2/#2-you-must-create-a-user-id-and-an-anonymous-id-field-in-marketo) in Marketo, you can upload a list of all your users with an email column and a userId column. Your CSV should look like this: | **email** | **userId** | | ----------------- | ---------- | | alex@email.com | ABC1234 | | natasha@email.com | XYZ9876 | -To upload a list to Marketo, when you are in Lead Database, click All Leads. Then click "New", then "Import List" from the drop down. Select your CSV, then click "Next". Make sure "Email Address" and "userId" are the Marketo Fields selected then click "Next". Name your list or select a pre-existing list. Select "None" for Acquisition Program. Then Click "Import". - -2. Manually merge leads in Marketo. Follow [these instructions to merge](http://docs.marketo.com/display/public/DOCS/Find+and+Merge+Duplicate+People){:target="_blank"} any duplicate leads found in Marketo after enabling the destination. -3. Make sure to call identify first. This is already a recommended best practice as [part of our spec](/docs/connections/spec/identify/). -4. Pass an email in your `.track()` and `.page()` calls. +To upload a list to Marketo, when you are in Lead Database: -## Migrating from Marketo to Marketo V2 +1. Click **All Leads**. +2. Then click **New**, then **Import List**. +3. Select your CSV, then click **Next**. Make sure `Email Address` and `userId` are the Marketo Fields selected then click **Next"**. +4. Name your list or select a pre-existing list. Select **None** for Acquisition Program. Then click **Import**. -There are a few necessary steps that have to be taken to migrate from Segment's legacy Marketo v1 destinations, to Marketo V2. +**Manually merge leads in Marketo**. -**Important: Make sure you disable Marketo once you are done getting set up with Marketo V2. If you leave both enabled, there will likely be duplicate data in your Marketo account.** +Follow [Marketo's instructions to merge](http://docs.marketo.com/display/public/DOCS/Find+and+Merge+Duplicate+People){:target="_blank"} any duplicate leads found in Marketo after enabling the destination. +1. Make sure to call Identify first. This is already a recommended best practice as [part of the Segment spec](/docs/connections/spec/identify/). +2. Pass an email in your Track and Page calls. -1. Your Marketo credentials in your Segment Destination settings need to be updated. Our Marketo Destination used Marketo's SOAP API and Marketo V2 uses Marketo's REST API which requires different credentials. Check out the [Getting Started](/docs/connections/destinations/catalog/marketo-v2/#getting-started) guide for what credentials you'll need. -2. Two custom fields must be created in Marketo: userId and anonymousId. Check out [Getting Started](/docs/connections/destinations/catalog/marketo-v2/#2-you-must-create-a-user-id-and-an-anonymous-id-field-in-marketo) for exact details on how to create these custom fields in Marketo. -3. `Track` calls must be mapped in your Destination settings. Our Marketo Destination sent `track` calls as a Munchkin Visit WebPage event in Marketo. In Marketo V2, we'll send your track calls to your Marketo Custom Activities. Detailed instructions [in the Track section of this page](/docs/connections/destinations/catalog/marketo-v2/#track). -4. If there are any custom Lead fields that you'd like sent to Marketo in your `Identify` calls, you must create custom fields in Marketo and add them in your Destination settings. In addition, if you are connecting Marketo V2 in Device-mode, an empty form must be created in Marketo to create and update leads. Detailed instructions [in the Identify section of this page](/docs/connections/destinations/catalog/marketo-v2/#identify). -5. Update anything in Marketo that rely on the way V1 sends `.track()` events to be triggered by your custom activities. For example, our V1 Marketo destination sent track events as a "Visit Web Page" event with `/event/`. So if you a workflow that is triggered by a "Visit Web Page" event where the web page contains `/event/`, you'll have to swap out the "Visit Web Page" event trigger you have with your Custom Attribute Trigger. In the right side bar, click the "Custom" folder under "Triggers" and select the trigger that you set for your custom activity: - ![A screenshot of the Smart List tab in Marketo.](images/cPD4kP65buG+.png) +## Migrating from Marketo to Marketo v2 +There are a few necessary steps that have to be taken to migrate from Segment's legacy Marketo v1 destinations, to Marketo v2. - To figure out what the trigger name for that Custom Activity is, navigate to the admin section of Marketo > Marketo Custom Activities > Click on your activity from the side bar and you'll see the trigger name: +> warning "" +> Make sure you disable Marketo once you set up with Marketo v2. If you leave both enabled, there might be duplicate data in your Marketo account. +1. Your Marketo credentials in your Segment Destination settings need to be updated. The Marketo destination used Marketo's SOAP API and Marketo v2 uses Marketo's REST API which requires different credentials. Check out the [getting started in Marketo v2](/docs/connections/destinations/catalog/marketo-v2/#getting-started) guide for the credentials you need. +2. Two custom fields must be created in Marketo: `userId` and `anonymousId`. Check out [getting started in Marketo v2](/docs/connections/destinations/catalog/marketo-v2/#2-you-must-create-a-user-id-and-an-anonymous-id-field-in-marketo) for exact details on how to create these custom fields in Marketo. +3. Track calls must be mapped in your destination settings. The Marketo Destination sent Track calls as a Munchkin Visit WebPage event in Marketo. In Marketo v2, your track calls are sent to your Marketo Custom Activities. See the instructions [in the Track section](/docs/connections/destinations/catalog/marketo-v2/#track) for more detail. +4. If there are any custom lead fields that you'd like sent to Marketo in your Identify calls, you must create custom fields in Marketo and add them in your destination settings. In addition, if you are connecting Marketo v2 in device-mode, an empty form must be created in Marketo to create and update leads. See the instructions [in the Identify section](/docs/connections/destinations/catalog/marketo-v2/#identify) for more detail. +5. Update anything in Marketo that rely on the way v1 sends Track events to be triggered by your custom activities. For example, the v1 Marketo destination sent track events as a "Visit Web Page" event with `/event/`. So if you have a workflow that is triggered by a "Visit Web Page" event where the web page contains `/event/`, you need to swap out the "Visit Web Page" event trigger with your Custom Attribute Trigger. Click the **Custom** folder under **Triggers** and select the trigger that you set for your custom activity: + ![A screenshot of the Smart List tab in Marketo.](images/cPD4kP65buG+.png) + > To figure out what the trigger name for that Custom Activity is, navigate to the **Admin** section of **Marketo > Marketo Custom Activities**, then click on your activity to see the trigger name: ![A screenshot of the Marketo Custom Activities field.](images/cg6YhDEPWXv+.png) +6. When enabling Marketo v2, because of the way Marketo's API works, there is potential to create duplicate leads, especially when the first enabling the destination. For ways to prevent this, check out the [Preventing Duplicate Leads](https://nation.marketo.com/t5/knowledgebase/working-with-duplicate-leads/ta-p/248189){:target="_blank"}. -6. When enabling Marketo V2, because of the way Marketo's API works, there is potential to create duplicate leads, especially when the first enabling the destination. For ways to prevent this, check out the Preventing Duplicate Leads. +## Send a single source's data to multiple Marketo v2 workspaces -## Send a single source's data to multiple Marketo V2 workspaces +Segment doesn't support multiple instances of Marketo v2 for any source in Segment (for both Device-Mode and Cloud-Mode). If you need a single source's data sent to multiple Marketo v2 workspaces, follow the instructions on configuring a [Repeater destination](/docs/connections/destinations/catalog/repeater/) to route your source's data through the Repeater destination into a new source and new Marketo v2 destination instance. -Segment doesn't support multiple instances of Marketo V2 for any source in Segment (for both Device-Mode and Cloud-Mode). If you need a single source's data sent to multiple Marketo V2 workspaces, follow the instructions on configuring a [Repeater destination](/docs/connections/destinations/catalog/repeater/) to route your source's data through the Repeater destination into a new source and new Marketo V2 destination instance. -To create a Repeater destination, new source, and second Marketo V2 destination: +To create a Repeater destination, new source, and second Marketo v2 destination: 1. Create and connect a new [Repeater destination](https://app.segment.com/goto-my-workspace/destinations/catalog/repeater) to your source and select the intended source. -2. Click **Add destination**, name the destination, and select Fill in settings manually. -4. Create a new source, then navigate to **Settings > API Keys** and copy the **Write Key** value. -- From the Repeater destination's **Settings** page, you'll find **Write Keys** in the **Connection Settings**. This is where your second source's write key from step 4 will go. +2. Click **Add destination**, name the destination, and select **Fill in settings manually**. +3. Create a new source, then navigate to **Settings > API Keys** and copy the **Write Key** value. + > From the Repeater destination's **Settings** page, find **Write Keys** in the **Connection Settings**. This is where your second source's write key from step 4 will go. 5. Navigate back to your Repeater destination and paste in the source's `writeKey` into the write key setting. -6. Add a Marketo V2 destination to your new source with the desired configuration settings. -7. Enable the Repeater destination, new source, new Marketo V2 destination. -8. You'll begin seeing data transmitted from your originating source to the Repeater Destination (Event Delivery), then to the new source (Debugger), and finally to the Marketo V2 destination (Event Delivery). +6. Add a Marketo v2 destination to your new source with the desired configuration settings. +7. Enable the Repeater destination, new source, new Marketo v2 destination. +8. Data is now transmitted from your originating source to the Repeater Destination (Event Delivery), then to the new source (Debugger), and finally to the Marketo v2 destination (Event Delivery). diff --git a/src/connections/destinations/catalog/marketo/index.md b/src/connections/destinations/catalog/marketo/index.md index 5771c4461a..deda0dc315 100644 --- a/src/connections/destinations/catalog/marketo/index.md +++ b/src/connections/destinations/catalog/marketo/index.md @@ -3,26 +3,27 @@ title: Marketo Destination strat: adobe --- -## Getting Started +## Getting started When you enable Marketo in the Segment web app, your changes appear in the Segment CDN in about 45 minutes, and then Analytics.js starts asynchronously loading Marketo's Munchkin onto your page. This means you should remove Marketo's snippet from your page. -+ Marketo starts automatically recording visitor information. -### Important Note: -Our client-side and server-side destinations each require **different** credentials for authentication. Read through the information below on `identify` calls for further information. +> info "" +> Marketo starts automatically recording visitor information. +> warning "" +> Client-side and server-side destinations each require **different** credentials for authentication. Read through [Identify](#identify) for further information. ## Page and Track -For [`Page`](/docs/connections/spec/page/) or [`Track`](/docs/connections/spec/track/) methods, Segment uses [Marketo's Munchkin.js `visitWebPage` method](http://developers.marketo.com/javascript-api/lead-tracking/api-reference/#munchkin_visitwebpage){:target="_blank"}. The URL is built from the Segment event and properties object into the form Marketo expects, so no need to worry about doing that yourself. +For [Page](/docs/connections/spec/page/) or [Track](/docs/connections/spec/track/) methods, Segment uses [Marketo's Munchkin.js `visitWebPage` method](http://developers.marketo.com/javascript-api/lead-tracking/api-reference/#munchkin_visitwebpage){:target="_blank"}. The URL is built from the Segment event and properties object into the form Marketo expects, so no need to worry about doing that yourself. -To associate Track events to a particular Lead in Marketo from a server side library, you will need to pass the Munchkin.js cookie with your track calls. +To associate Track events to a particular Lead in Marketo from a server side library, you need to pass the Munchkin.js cookie with your track calls. ## Identify ### Client-side -When you call [`identify`](/docs/connections/spec/identify/) on Analytics.js, we call Marketo's [`associateLead`](http://developers.marketo.com/documentation/websites/lead-tracking-munchkin-js/){:target="_blank"}. Marketo **requires an email address** for this function, so if the `traits` object you include in [`identify`](/docs/connections/spec/identify/) doesn't have an email, the request won't go through. Marketo's client-side library, [Munchkin](http://developers.marketo.com/documentation/websites/lead-tracking-munchkin-js/){:target="_blank"}, **requires your API private key** for authentication along with your email, so make sure that you have provided it in your Segment settings. We will not change the casing of traits on client-side identify calls. +When you call [Identify](/docs/connections/spec/identify/) on Analytics.js, Segment calls Marketo's [`associateLead`](http://developers.marketo.com/documentation/websites/lead-tracking-munchkin-js/){:target="_blank"}. Marketo **requires an email address** for this function, so if the `traits` object you include in [Identify](/docs/connections/spec/identify/) doesn't have an email, the request won't go through. Marketo's client-side library, [Munchkin](http://developers.marketo.com/documentation/websites/lead-tracking-munchkin-js/){:target="_blank"}, **requires your API private key** for authentication along with your email, so make sure that you have provided it in your Segment settings. Segment doesn't change the casing of traits on client-side identify calls. ```javascript analytics.identify('1234', { @@ -33,21 +34,21 @@ analytics.identify('1234', { }); ``` -In order to properly sign the `associateLead` request while keeping your account and data secure, we make a request to our API that calculates the appropriate SHA1 security hash for the user you're identifying. We use this hash to sign the `associateLead` request to Marketo. +In order to properly sign the `associateLead` request while keeping your account and data secure, Segment makes a request to our API that calculates the appropriate SHA1 security hash for the user you're identifying. This hash is used to sign the `associateLead` request to Marketo. -Note that we will automatically send `userId` as a trait. Normally, the `userId` was sent as an `id` inside the traits but Marketo silently ignores that field as they use it for their own purposes. So if you create a custom field inside Marketo for `userId`, your leads will automatically have that field populated. +Note that Segment automatically sends `userId` as a trait. Normally, the `userId` was sent as an `id` inside the traits but Marketo silently ignores that field as they use it for their own purposes. So if you create a custom field inside Marketo for `userId`, your leads automatically have that field populated. ### Server Side -When you can [`identify`](/docs/connections/spec/identify/) with a `traits` object on any of the server-side languages, we make a call to Marketo's `syncLead` SOAP API action. This call either creates or a updates `traits` on a lead based on the email address either in `userId` or `traits.email`. +When you call [Identify](/docs/connections/spec/identify/) with a `traits` object on any of the server-side languages, Segment makes a call to Marketo's `syncLead` SOAP API action. This call either creates or a updates `traits` on a lead based on the email address either in `userId` or `traits.email`. -We will attempt to PascalCase server-side traits. So if you send `secondFavoriteColor` as a trait, we will convert that to `SecondFavoriteColor`, so you should set the trait **API name** in Marketo to `SecondFavoriteColor`. If you send the trait as `second_favorite_color`, we will convert that to `Second_favorite_color`, so you should set the API name to be `Second_favorite_color` (this is less than ideal; however, we plan to update this behavior in v2 of our Marketo destination, so stay tuned!). +Segment attempts to PascalCase server-side traits. So if you send `secondFavoriteColor` as a trait it's converted to `SecondFavoriteColor`, so you should set the trait **API name** in Marketo to `SecondFavoriteColor`. If you send the trait as `second_favorite_color` it's converted to `Second_favorite_color`, so you should set the API name to be `Second_favorite_color`. -Note that leads can only be synced every 30 seconds using the SOAP API. If you exceed the allowed request amount, you will see `Exceeded lock attempts` errors in your debugger. +Note that leads can only be synced every 30 seconds using the SOAP API. If you exceed the allowed request amount, the `Exceeded lock attempts` errors appear in your debugger. -Our server side destination with Marketo **requires your encryption key** along with your email for authentication, make sure you have provided it in your Segment settings. +The server-side destination with Marketo **requires your encryption key** along with your email for authentication, make sure you have provided it in your Segment settings. -Remember to provide an email with every call as either the `userId` or as a trait labeled "email". Here's a java example of that: +Remember to provide an email with every call as either the `userId` or as a trait labeled "email". Here's a Java example of that: ```java Analytics.identify("hj2kf92ds212", @@ -58,13 +59,13 @@ Analytics.identify("hj2kf92ds212", Marketo uses cookies to keep track of visitors and their sessions while visiting your website. The cookie data is stored in the visitor's browser, and is sent along to Marketo every time a new event occurs. This allows them to show a single unique lead between multiple page reloads. -Your servers also have access to this cookie, so they can re-use it when you send server-side events to Segment. If you don't use the existing cookie Segment will use either the userId or sessionId to make the server-side request to Marketo. When we create a new cookie, the client-side and server-side events from the same user will look like two distinct leads when viewed in Marketo. The cookieId takes precedence over all other keys, so if you send both the cookieId and the userId - the cookieId will match first and the userId for that lead will be updated. +Your servers also have access to this cookie, so they can re-use it when you send server-side events to Segment. If you don't use the existing cookie, Segment uses either the `userId` or `sessionId` to make the server-side request to Marketo. When a new cookie is created, the client-side and server-side events from the same user look like two distinct leads when viewed in Marketo. The `cookieId` takes precedence over all other keys, so if you send both the `cookieId` and the `userId` - the `cookieId` matches first and the `userId` for that lead is updated. To associate leads in server-side Marketo, there are currently three options with Segment: 1. Pass your Marketo cookies to Segment. -2. Use the userId or sessionId when associating leads in Marketo. -3. Ignore the additional visitors generated by passing different types of ids for each call (i.e. cookieId once, then the userId for the same user the second time). +2. Use the `userId` or `sessionId` when associating leads in Marketo. +3. Ignore the additional visitors generated by passing different types of IDs for each call - `cookieId` once, then the `userId` for the same user the second time. If you choose to pass the cookie with your calls, it will look like this: @@ -72,7 +73,7 @@ If you choose to pass the cookie with your calls, it will look like this: id:561-HYG-937&token:_mch-marketo.com-1374552656411-90718 ``` -If you want our server-side destination to use your user's Marketo Cookie, pass it to us in the `context['Marketo'].marketoCookie` object. +If you want our server-side destination to use your user's Marketo Cookie, pass it to Segment in the `context['Marketo'].marketoCookie` object. Here's a Ruby example: @@ -92,9 +93,9 @@ Analytics.identify( ) ``` -**Note:** If you choose to use the cookie approach, make sure to send the cookie along in your `track` calls as well, as Marketo will need it on subsequent calls to tie activity to that user. +**Note:** If you choose to use the cookie approach, make sure to send the cookie along in your Track calls as well. Marketo needs it on subsequent calls to tie activity to that user. -A `track` call might look like this: +A Track call might look like this: ```ruby Analytics.track( @@ -113,10 +114,10 @@ Analytics.track( ) ``` -For more information about syncronising your Marketo leads, [visit their documentation](http://developers.marketo.com/documentation/soap/synclead/){:target="_blank"}. +For more information about syncronising your Marketo leads, [visit the Marketo documentation](http://developers.marketo.com/documentation/soap/synclead/){:target="_blank"}. -### Custom Fields +### Custom fields -To create a custom field in Marketo, follow Marketo's [documentation for creating a custom field](http://docs.marketo.com/display/public/DOCS/Create+a+Custom+Field+in+Marketo){:target="_blank"}. Be sure that the **API Name** is `PascalCase`'d, as our destination will account for Marketo's Pascal trait standards. +To create a custom field in Marketo, follow Marketo's [documentation for creating a custom field](http://docs.marketo.com/display/public/DOCS/Create+a+Custom+Field+in+Marketo){:target="_blank"}. Be sure that the **API Name** is `PascalCase`'d, as the destination accounts for Marketo's Pascal trait standards. -For instance, if you configure `SomeTrait` in the **API Name** field (the **Name** value does not matter), you can pass in this field as `someTrait`, and we will convert this to `SomeTrait` when sending into Marketo. Note that if you configured **API Name** to be `someTrait`, and passed it in as `someTrait` in your call, this would fail to send. +For instance, if you configure `SomeTrait` in the **API Name** field (the **Name** value does not matter), you can pass in this field as `someTrait`. Segment converts this to `SomeTrait` when sending into Marketo. Note that if you configured **API Name** to be `someTrait` and passed it in as `someTrait` in your call, this would fail to send. diff --git a/src/connections/destinations/catalog/matomo/index.md b/src/connections/destinations/catalog/matomo/index.md index 05fd9b04a1..9435ea6470 100644 --- a/src/connections/destinations/catalog/matomo/index.md +++ b/src/connections/destinations/catalog/matomo/index.md @@ -7,17 +7,15 @@ id: 54521fda25e721e32a72eee7 [Matomo](https://matomo.org/){:target="_blank"}, formerly Piwik, is the leading open source web analytics platform that gives you valuable insights into your website's visitors, your marketing campaigns and much more, so you can optimize your strategy and online experience of your visitors. Segment’s Matomo destination code is open-source and can be viewed on GitHub: -- [Javascript](https://github.com/segmentio/analytics.js-integrations/blob/master/integrations/piwik/lib/index.js){:target="_blank"} - -## Getting Started - +- [Javascript](https://github.com/segmentio/analytics.js-integrations/blob/master/integrations/piwik/lib/index.js){:target="_blank"}. +## Getting started 1. From the Segment web app, click **Catalog**. -2. Search for "Matomo" in the Catalog, select it, and choose which of your sources to connect the destination to. Note the source must be sending events using our JavaScript library Analytics.js. +2. Search for "Matomo" in the Catalog, select it, and choose which of your sources to connect the destination to. Note the source must be sending events using the Segment JavaScript library Analytics.js. 3. In the destination settings, enter your Site ID. You can find your Site ID in your Matomo snippet. -4. In the destination settings, enter your Server URL. You can find your Server URL in your snippet, we will append /matomo.php to the URL automatically. - 5. When you enable Matomo in your Segment settings, Segment's CDN is updated within 45 minutes. Once that happens, Segment asynchronously loads `matomo.js` on your page whenever it is loaded. This means you should remove Matomo's snippet from your page. +4. In the destination settings, enter your Server URL. You can find your Server URL in your snippet. Segment automatically appends /matomo.php to the URL. +5. When you enable Matomo in your Segment settings, Segment's CDN is updated within 45 minutes. Once that happens, Segment asynchronously loads `matomo.js` on your page whenever it is loaded. This means you should remove Matomo's snippet from your page. ## Page If you're not familiar with the Segment Specs, take a look to understand what the [Page method](/docs/connections/spec/page/) does. An example call would look like: @@ -25,8 +23,7 @@ If you're not familiar with the Segment Specs, take a look to understand what th ```js analytics.page(); ``` - -Our Page method triggers a call to Matomo's `trackPageView` method. +The Page method triggers a call to Matomo's `trackPageView` method. ## 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: @@ -34,7 +31,7 @@ If you're not familiar with the Segment Specs, take a look to understand what th ```js analytics.identify('97980cfea0068'); ``` -Our Identify method triggers a call to Matomo's `setUserId` method and will send the `userId` to Matomo. +The Identify method triggers a call to Matomo's `setUserId` method and will send the `userId` to Matomo. ## 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: @@ -43,9 +40,9 @@ If you're not familiar with the Segment Specs, take a look to understand what th analytics.track('Logged In'); ``` -We'll record a Matomo event whenever you make a `track` call. +Segement records a Matomo event whenever you make a `track` call. -For the example above, these event attributes are sent to Matomo: +In the example, these event attributes are sent to Matomo: @@ -58,7 +55,7 @@ For the example above, these event attributes are sent to Matomo:
-Find below another Track example, this time with all the available Matomo event parameters: +See the following Track example, this time with all the available Matomo event parameters: ```js analytics.track('Created Account', { @@ -68,7 +65,7 @@ analytics.track('Created Account', { }) ``` -That call will create a Matomo Event with these attributes: +That call creates a Matomo Event with these attributes: @@ -89,17 +86,18 @@ That call will create a Matomo Event with these attributes:
-For **Event Value** you can name the event property `value` or `revenue`. We'll look for `value` first, then fall back to `revenue`. +For **Event Value**, you can name the event property `value` or `revenue`. Segment looks for `value` first, then fall back to `revenue`. -## Best Pratices +## Best practices -Matomo allows you to set [custom variables](http://matomo.org/docs/custom-variables/){:target="_blank"} with your pageviews and events. With Segment, you can set page-scoped custom variables with any `track` call you make with analytics.js. +Matomo lets you set [custom variables](http://matomo.org/docs/custom-variables/){:target="_blank"} with your pageviews and events. With Segment, you can set page-scoped custom variables with any Track call you make with analytics.js. -Since these custom variables must be mapped to an index you define, which can change from call to call, the only way we can support these custom variables with full flexibility is to allow you to pass your map in the `context.Matomo.customVars` dictionary of each call. +Since these custom variables must be mapped to an index you define, which can change from call to call, the only way that Segment can support these custom variables with full flexibility is to allow you to pass your map in the `context.Matomo.customVars` dictionary of each call. -To take advantage of this feature, your `track` calls should look like this: +To take advantage of this feature, your Track calls should look like this: -> **Note** The destination's name is still "piwik" in the JSON for these calls. +> info "" +> The destination's name is still "piwik" in the JSON for these calls. ```js analytics.track('event', { @@ -117,6 +115,6 @@ analytics.track('event', { ``` ### Goals -If you want to flag specific events as Matomo Goals you can do so by mapping those events in your Segment Source Destinations page under Matomo Settings. +If you want to flag specific events as Matomo Goals, you can do so by mapping those events in your Segment Source Destinations page under Matomo Settings. -Fill in the event on the left and the Goal ID from Matomo on the right. Then every time the event happens we'll fire Matomo's `trackGoal` method. +Fill in the event on the left and the Goal ID from Matomo on the right. Then every time the event happens Segment fires Matomo's `trackGoal` method. diff --git a/src/connections/destinations/catalog/moengage/index.md b/src/connections/destinations/catalog/moengage/index.md index a999d033f4..c4145d435a 100644 --- a/src/connections/destinations/catalog/moengage/index.md +++ b/src/connections/destinations/catalog/moengage/index.md @@ -5,12 +5,11 @@ id: 55b280290a20f4e22f0fb3d6 hide-personas-partial: true --- -[MoEngage](https://www.moengage.com/){:target="_blank"} is an Intelligent Customer Engagement Platform. MoEngage allows brands to personalize every customer interaction and drive better engagement, retention, loyalty and lifetime value. +[MoEngage](https://www.moengage.com/){:target="_blank"} is an intelligent customer engagement platform. MoEngage allows brands to personalize every customer interaction and drive better engagement, retention, loyalty and lifetime value. -The MoEngage and Segment integration allows you to send -the users you have tracked on Segment, along with their route data, to MoEngage for further targeting and campaigning. This Destination enables you to: +The MoEngage and Segment integration allows you to send the users you have tracked on Segment, along with their route data, to MoEngage for further targeting and campaigning. This destination enables you to: -- **Import data from Segment to MoEngage**: Moengage offers a side-by-side (device mode) SDK integration for your Android, iOS, and web applications and a server-to-server integration for your backend services. +- **Import data from Segment to MoEngage**: Moengage offers a side-by-side (device-mode) SDK integration for your Android, iOS, and web applications and a server-to-server integration for your backend services. - **Sync [Twilio Engage](https://segment.com/product/twilio-engage){:target="_blank"} (cohorts)**: Send Segment Cohorts to MoEngage for use in MoEngage Segments and campaigns. The MoEngage Destination source code is open-sourced and freely available on GitHub for anyone to view: @@ -21,33 +20,31 @@ Connection Mode | Maintained by | GitHub Link Android | MoEngage | [moengage-segment-integration](https://github.com/moengage/moengage-segment-integration){:target="_blank"} Web | Segment | [analytics.js-integrations](https://github.com/segmentio/analytics.js-integrations/tree/master/integrations/moengage){:target="_blank"} -## Getting Started +## Getting started -Once you add the Segment-MoEngage library to your app, you can enable MoEngage from the Segment App. These new settings can take up to an hour to propagate to your existing users. For new users, it'll be instantaneous! +Once you add the Segment-MoEngage library to your app, you can enable MoEngage from the Segment App. These new settings can take up to an hour to propagate to your existing users. For new users, the settings are propagated instantly. The Segment-MoEngage Integration is a bundled integration, meaning it requires that you add a client-side integration to your app. -## Setup MoEngage in your Segment Workspace +## Setup MoEngage in your Segment workspace To setup MoEngage do the following : - 1. First get your key(AppID) from the MoEngage dashboard. Navigate to `Dashboard --> Settings --> App --> General`. - 2. Go to your **Segment workspace**, go to **Destinations** and select **MoEngage**. + 1. First get your key(AppID) from the MoEngage dashboard. Navigate to **Dashboard > Settings > App > General**. + 2. In your Segment workspace, go to **Destinations** and select **MoEngage**. 3. Enable the MoEngage Destination. - 4. Go to the MoEngage Settings and enter the MoEngage AppID, obtained in **Step1**. + 4. Go to the MoEngage Settings and enter the MoEngage AppID, obtained in Step 1. 5. Save the changes. - 6. Make sure you set the **Connection Mode** to `Device Mode`. MoEngage requires this setting to use - of features like push notifications and any in-app features of the MoEngage SDK. + 6. Make sure you set the **Connection Mode** to `Device Mode`. MoEngage requires this setting to use of features like push notifications and any in-app features of the MoEngage SDK. -These new settings will take up to an hour to propagate to your existing users. For new -users it'll be instantaneous! Segment-MoEngage Integration is a bundled integration, requires client side integration. +Segment-MoEngage Integration is a bundled integration and requires client-side integration. -![segment_settings.png](images/segment_settings.png) + ![Screenshot of MoEngage Settings page](images/segment_settings.png) ## Identify Use [Identify](/docs/connections/sources/catalog/libraries/mobile/android/#identify) to track user-specific attributes. This is the same as tracking [user attributes](https://help.moengage.com/hc/en-us/articles/360044285511-User-Profile){:target="_blank"} on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. If you set `traits.id`, MoEngage sets that as the Unique ID for that user. > info "" -> MoEngage supports anonymous identifiers in Device-mode only. If you use the MoEngage destination in Cloud-mode, use a known user identifier. +> MoEngage supports anonymous identifiers in device-mode only. If you use the MoEngage destination in cloud-mode, use a known user identifier. The Identify method follows the format below: @@ -59,7 +56,7 @@ analytics.identify('12090000-00001992', { ``` ## Track -Use [track](/docs/connections/sources/catalog/libraries/mobile/android/#track) to track events and user behavior in your app. +Use [Track](/docs/connections/sources/catalog/libraries/mobile/android/#track) to track events and user behavior in your app. ```javascript analytics.track('Article Completed', { @@ -68,30 +65,30 @@ analytics.track('Article Completed', { }); ``` -This will send the event to MoEngage with the associated properties. Tracking events is essential and will help you create segments for engaging users. +This sends the event to MoEngage with the associated properties. Tracking events is essential and helps you create segments for engaging users. ## Reset -If your app or website supports the ability for a user to logout and login with a new identity, then you'll need to call [reset](/docs/sources/website/analytics.js/#reset-logout) method in `analytics.js`. +If your app or website supports the ability for a user to logout and login with a new identity, then you need to call the [Reset](/docs/sources/website/analytics.js/#reset-logout) method in `analytics.js`. ```javascript analytics.reset(); ``` ## iOS - To get started with MoEngage on iOS, first integrate your app with the [MoEngage-Segment-Swift](https://github.com/moengage/MoEngage-Segment-Swift){:target="_blank"} library. You can integrate MoEngage and Segment with Swift Package Manager. > info "" -> **Note:** This document covers the integration with [analytics-swift](https://github.com/segmentio/analytics-swift){:target="_blank"}, if you have integrated with [analytics-ios](https://github.com/segmentio/analytics-ios){:target="_blank"} refer [this documentation](https://partners.moengage.com/hc/en-us/articles/4409143473172-iOS-device-mode-){:target="_blank"} for details on how to integrate. +> This document covers the integration with [analytics-swift](https://github.com/segmentio/analytics-swift){:target="_blank"}. If you've integrated with [analytics-ios](https://github.com/segmentio/analytics-ios){:target="_blank"} refer [MoEngage's documentation](https://partners.moengage.com/hc/en-us/articles/4409143473172-iOS-device-mode-){:target="_blank"} for details on how to integrate. - To install with SPM use the [MoEngage-Segment-Swift](https://github.com/moengage/MoEngage-Segment-Swift.git){:target="_blank"} library and set the branch as master or version as 1.0.0 and above. +To install with SPM use the [MoEngage-Segment-Swift](https://github.com/moengage/MoEngage-Segment-Swift.git){:target="_blank"} library and set the branch as master or version as 1.0.0 and above. ### Configure the Segment SDK: -Now head to the App Delegate file, and setup the Segment SDK by +Head to the App Delegate file, and setup the Segment SDK by: + 1. Importing `Segment`, `Segment_MoEngage` and `MoEngageSDK`. 2. Initialize `MoEngageSDKConfig` object and call `initializeDefaultInstance` method of `MoEngageInitializer`. -3. Initialize `MoEngageDestination` as shown below: +3. Initialize `MoEngageDestination`: Under your Analytics-Swift library setup, add the MoEngage plugin using the `analytics.add(plugin: ...)` method. The MoEngage dashboard now tracks all of your events. @@ -116,43 +113,42 @@ analytics.add(plugin: MoEngageDestination()) } ``` -### Tracking User Attribute +### Tracking user attribute -[User attributes](https://developers.moengage.com/hc/en-us/articles/4403905883796-Tracking-user-attributes){:target="_blank"} are specific traits of a user, like email, username, mobile, gender etc. **identify** lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them. +[User attributes](https://developers.moengage.com/hc/en-us/articles/4403905883796-Tracking-user-attributes){:target="_blank"} are specific traits of a user, like email, username, mobile, gender, and more. Identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them. ```swift Analytics.main.identify("a user's id", traits: @["email":"a user's email address"]) ``` -Read more about [identify calls](/docs/connections/sources/catalog/libraries/mobile/ios/#identify). +Read more about [Identify calls](/docs/connections/sources/catalog/libraries/mobile/ios/#identify) for further detail. -### Tracking Events +### Tracking events -Segment uses event tracking to track user behavior in an app. `track` calls let you record the actions your users perform. Every action triggers an "event", which can also have associated attributes. +Segment uses event tracking to track user behavior in an app. Track calls let you record the actions your users perform. Every action triggers an "event", which can also have associated attributes. ```swift Analytics.main.track("Item Purchased", properties: @["item":"Sword of Heracles"]) ``` -Read more about [track calls](/docs/connections/sources/catalog/libraries/mobile/ios/#track). - +Read more about [Track calls](/docs/connections/sources/catalog/libraries/mobile/ios/#track) for further detail. -### Reset Users +### Reset users -The `reset` method clears the SDK's internal stores for the current user. This is useful for apps where users can log in and out with different identities over time. +The Reset method clears the SDK's internal stores for the current user. This is useful for apps where users can log in and out with different identities over time. ```swift Analytics.main.reset() ``` -Read more about the [reset method](/docs/connections/sources/catalog/libraries/mobile/ios/#reset). +Read more about the [Reset method](/docs/connections/sources/catalog/libraries/mobile/ios/#reset) for further detail. -### Install / Update Differentiation +### Install or update differentiation Since your app might already be on the App Store, you must specify whether your app update would be an `UPDATE` or an `INSTALL`. -To differentiate between those, use one of the method below: +To differentiate between those, use one of the following methods: ```swift //For new Install call following @@ -162,20 +158,20 @@ To differentiate between those, use one of the method below: MoEngageSDKAnalytics.sharedInstance.appStatus(.update) ``` -Read more on [install/update differentiation](https://developers.moengage.com/hc/en-us/articles/4403910297620){:target="_blank"}. +Read more on [Install/Update differentiation](https://developers.moengage.com/hc/en-us/articles/4403910297620){:target="_blank"} on MoEngage website. ### Set the data center -By default, the data center setting in the SDK is set to `data_center_01`. Follow the steps in the [MoEngage - Data Center](https://developers.moengage.com/hc/en-us/articles/4403910162452-Data-Center){:target="_blank"} to update the data center value. If not set correctly, several features of the MoEngage SDK will not function. +By default, the data center setting in the SDK is set to `data_center_01`. Follow the steps in the [MoEngage - Data Center](https://developers.moengage.com/hc/en-us/articles/4403910162452-Data-Center){:target="_blank"} to update the data center value. If not set correctly, several features of the MoEngage SDK won't function. -## MoEngage iOS SDK Features +## MoEngage iOS SDK features Along with tracking your user's activities, you can use the MoEngage iOS SDK for more effective user engagement: -### Push Notifications: -Push Notifications are a great way to keep your users engaged and informed about your app. You have following options while implementing push notifications in your app: +### Push notifications: +Push notifications are a useful way to keep your users engaged and informed about your app. You have following options while implementing push notifications in your app: -**Segment Push Implementation:** +**Segment push implementation:** 1. In your application's application:didRegisterForRemoteNotificationsWithDeviceToken: method, add the following: ```swift @@ -197,24 +193,21 @@ Push Notifications are a great way to keep your users engaged and informed about Analytics.main.handleAction(identifier: identifier, userInfo: userInfo) ``` -**MoEngage Push Implementation:** +**MoEngage push implementation:** For information about the MoEngage push implementation, see [**Push Notifications**](https://developers.moengage.com/hc/en-us/articles/4403943988756){:target="_blank"} in the MoEngage documentation. ### In-app messaging -In-App Messages are custom views which you can send to a set of users to show custom messages, give new offers, or direct to a specific page. For more information about In-app messaging, see [MoEngage - In-App NATIV](https://developers.moengage.com/hc/en-us/articles/4404155127828-In-App-Nativ){:target="_blank"}. - +In-app messages are custom views which you can send to a set of users to show custom messages, give new offers, or direct to a specific page. For more information about in-app messaging, see [MoEngage - In-App NATIV](https://developers.moengage.com/hc/en-us/articles/4404155127828-In-App-Nativ){:target="_blank"}. ### Cards Create targeted or automated App Inbox/NewsFeed messages that can be grouped into various categories, and target your users with different updates or offers that can stay in the Inbox/Feed over a designated period of time. For more information about cards, see [MoEngage - Cards](https://developers.moengage.com/hc/en-us/articles/4404058438676-Cards-in-iOS){:target="_blank"}. - ### Compliance -To make the App compliant with policies (such as GDPR) while using MoEngage's SDK, follow the instructions in this [doc](https://developers.moengage.com/hc/en-us/articles/4403905438228-SDK-initialisation){:target="_blank"}. - -### Segment Docs -For more info on using **Segment for iOS** refer to [**Developer Docs**](/docs/connections/sources/catalog/libraries/mobile/ios/) provided by Segment. +To make the app compliant with policies (such as GDPR) while using MoEngage's SDK, follow the instructions in [MoEngage's documentation](https://developers.moengage.com/hc/en-us/articles/4403905438228-SDK-initialisation){:target="_blank"}. +### Segment for iOS +For more info on using Segment for iOS, refer to the [Developer docs](/docs/connections/sources/catalog/libraries/mobile/ios/) provided by Segment. ## Android @@ -222,14 +215,14 @@ To use MoEngage in an Android app, you must perform the following steps to set u ![MavenBadge](https://maven-badges.herokuapp.com/maven-central/com.moengage/moengage-segment-kotlin-destination/badge.svg) -To enable the full functionality of MoEngage (like Push Notifications, InApp Messaging), complete the following steps in your Android app. +To enable the full functionality of MoEngage (like push notifications, in-app messaging), complete the following steps in your Android app. > info "" -> **Note:** This document covers the integration with [analytics-kotlin](https://github.com/segmentio/analytics-kotlin){:target="_blank"}, if you have integrated with [analytics-android](https://github.com/segmentio/analytics-android){:target="_blank"} refer [this documentation](https://partners.moengage.com/hc/en-us/articles/4409143473172-iOS-device-mode-){:target="_blank"} for details on how to integrate. +> This document covers the integration with [analytics-kotlin](https://github.com/segmentio/analytics-kotlin){:target="_blank"}. If you have integrated with [analytics-android](https://github.com/segmentio/analytics-android){:target="_blank"} refer [MoEngage's documentation](https://partners.moengage.com/hc/en-us/articles/4409143473172-iOS-device-mode-){:target="_blank"} for details on how to integrate. -### Adding the MoEngage Dependency +### Adding the MoEngage dependency -Along with the Segment dependency, add the below dependency in your `build.gradle` file. +Along with the Segment dependency, add the following dependency in your `build.gradle` file. ```groovy implementation("com.moengage:moengage-segment-kotlin-destination:$sdkVersion") { @@ -238,20 +231,18 @@ implementation("com.moengage:moengage-segment-kotlin-destination:$sdkVersion") { ``` with `$sdkVersion` replaced by the latest version of the MoEngage SDK. -The MoEngage SDK depends on the below Jetpack libraries provided by Google for its functioning, make you add them if not - done already. +The MoEngage SDK depends on the following Jetpack libraries provided by Google for its functioning, make sure you add them if not done already. ```groovy implementation("androidx.core:core:1.6.0") implementation("androidx.appcompat:appcompat:1.3.1") implementation("androidx.lifecycle:lifecycle-process:2.4.0") ``` -Refer to the [SDK Configuration](https://developers.moengage.com/hc/en-us/articles/4401984733972-Android-SDK-Configuration){:target="_blank"} documentation to know more about the build config and other libraries used by the SDK. +Refer to the [SDK Configuration](https://developers.moengage.com/hc/en-us/articles/4401984733972-Android-SDK-Configuration){:target="_blank"} documentation to learn more about the build config and other libraries used by the SDK. ### Register MoEngage with Segment SDK -After adding the dependency, you must register the integration with Segment SDK. To do this, import the MoEngage - integration: +After adding the dependency, you must register the integration with Segment SDK. To do this, import the MoEngage integration: ```kotlin import com.segment.analytics.kotlin.destinations.moengage.MoEngageDestination @@ -264,37 +255,36 @@ Analytics("", context) .add(MoEngageDestination(application)) ``` - ### Initialize the MoEngage SDK -Copy the APP ID from the Settings Page `Dashboard --> Settings --> App --> General` and initialize the MoEngage SDK in the onCreate method of the `Application` class +Copy the APP ID from the Settings page **Dashboard > Settings > App > General** and initialize the MoEngage SDK in the onCreate method of the `Application` class > info "" -> **Note:** MoEngage recommend that you initialize the SDK on the main thread inside `onCreate()` and not create a worker thread and initialize the SDK on that thread. +> MoEngage recommends that you initialize the SDK on the main thread inside `onCreate()` and not create a worker thread and initialize the SDK on that thread. ```kotlin -// this is the instance of the application class and "YOUR_APP_ID" is the APP ID from the dashboard. +// This is the instance of the application class and "YOUR_APP_ID" is the APP ID from the dashboard. val moEngage = MoEngage.Builder(this, "YOUR_APP_ID") .enablePartnerIntegration(IntegrationPartner.SEGMENT) .build() MoEngage.initialiseDefaultInstance(moEngage) ``` -### Exclude MoEngage Storage File from Auto-Backup -Auto backup service of Android periodically backs up the Shared Preference file, Database files, and so on. +### Exclude MoEngage storage file from auto-backup + +The auto-backup service of Android periodically backs up the Shared Preference file, Database files, and so on. -For more information, refer to [Auto Backup](https://developer.android.com/guide/topics/data/autobackup){:target="_blank"}. +For more information, refer to the [Auto-Backup](https://developer.android.com/guide/topics/data/autobackup){:target="_blank"} documentation. -As a result of the backup, MoEngage SDK identifiers are backed up and restored after re-install. -The restoration of the identifier results in your data being corrupted and the user not being reachable using push notifications. +As a result of the backup, MoEngage SDK identifiers are backed up and restored after re-install. The restoration of the identifier results in your data being corrupted and the user not being reachable using push notifications. To ensure data isn't corrupted after a backup is restored, opt-out of MoEngage SDK storage files. -Refer to the [documentation](https://developers.moengage.com/hc/en-us/articles/4401999257236-Exclude-MoEngage-Storage-File-from-Auto-Backup){:target="_blank"} for further details. +Refer to the [MoEngage documentation](https://developers.moengage.com/hc/en-us/articles/4401999257236-Exclude-MoEngage-Storage-File-from-Auto-Backup){:target="_blank"} for further details. ### Install or update differentiation This is required for migrations to the MoEngage Platform so the SDK can determine whether the user is a new user on your app, or an existing user who updated to the latest version. -If the user was already using your application and has just updated to a new version which has the MoEngage SDK, below is an example call: +If the user was already using your application and has just updated to a new version which has the MoEngage SDK. An example call: ```kotlin MoEAnalyticsHelper.setAppStatus(context, AppStatus.UPDATE) @@ -306,23 +296,19 @@ If this is a fresh install: MoEAnalyticsHelper.setAppStatus(context, AppStatus.INSTALL) ``` -## MoEngage Android SDK Features -### Configure Push Notifications +## MoEngage Android SDK features +### Configure push notifications -Copy the Server Key from the FCM console and add it to the MoEngage Dashboard. To upload it, go to the Settings Page `Dashboard --> Settings --> Channel --> Push --> Mobile Push --> Android` and add the Server Key and package name. -**Please make sure you add the keys both in Test and Live environment.** +Copy the Server Key from the FCM console and add it to the MoEngage Dashboard. To upload it, go to the Settings page, **Dashboard > Settings > Channel > Push > Mobile Push > Android** and add the Server Key and package name. Ensure that you add the keys both in Test and Live environment. #### Add meta information for push notification To display push notifications, some metadata regarding the notification is required. For example, the small icon and large icon drawables are mandatory. - Refer to the [MoEngage - NotificationConfig](https://moengage.github.io/android-api-reference-v11/core/com.moengage.core.config/-notification-config/index.html){:target="_blank"} API reference for all the possible options. - Use the `configureNotificationMetaData()` to pass on the configuration to the SDK. - ```kotlin val moEngage = MoEngage.Builder(this, "YOUR_APP_ID") .enablePartnerIntegration(IntegrationPartner.SEGMENT) @@ -334,9 +320,9 @@ Use the `configureNotificationMetaData()` to pass on the configuration to the SD MoEngage.initialiseDefaultInstance(moEngage) ``` -#### Configuring Firebase Cloud Messaging +#### Configuring Firebase cloud messaging -For showing Push notifications there are 2 important steps: +To show push notifications there are two important steps: 1. Registration for Push, for example generating push token. 2. Receiving the Push payload from Firebase Cloud Messaging(FCM) service and showing the notification on the device. @@ -345,7 +331,7 @@ For showing Push notifications there are 2 important steps: ###### Opt-out of MoEngage registration -To opt-out of MoEngage token registration mechanism disable token registration while configuring FCM in the `MoEngage.Builder` as shown below +To opt-out of MoEngage token registration mechanism disable token registration while configuring FCM in the `MoEngage.Builder`: ```kotlin val moEngage = MoEngage.Builder(this, "YOUR_APP_ID") @@ -361,19 +347,18 @@ To opt-out of MoEngage token registration mechanism disable token registration w ###### Pass the push token to the MoEngage SDK -The Application must pass the Push Token received from FCM to the MoEngage SDK for the MoEngage platform to send out push notifications to the device. -Use the below API to pass the push token to the MoEngage SDK. +The application must pass the Push Token received from FCM to the MoEngage SDK for the MoEngage platform to send out push notifications to the device. +Use the following API to pass the push token to the MoEngage SDK. ```kotlin MoEFireBaseHelper.getInstance().passPushToken(applicationContext,token) ``` -Please make sure token is passed to MoEngage SDK whenever push token is refreshed and on application update. Passing token on application update is important for migration to the MoEngage Platform. +Ensure that the token is passed to MoEngage SDK whenever push token is refreshed and on application update. Passing token on application update is important for migration to the MoEngage Platform. -###### Passing the Push payload to the MoEngage SDK +###### Passing the push payload to the MoEngage SDK -To pass the push payload to the MoEngage SDK call the MoEngage API from the `onMessageReceived()` from the Firebase receiver. -Before passing the payload to the MoEngage SDK you should check if the payload is from the MoEngage platform using the helper API provided by the SDK. +To pass the push payload to the MoEngage SDK call the MoEngage API from the `onMessageReceived()` from the Firebase receiver. Before passing the payload to the MoEngage SDK, check if the payload is from the MoEngage platform using the helper API provided by the SDK. ```kotlin if (MoEPushHelper.getInstance().isFromMoEngagePlatform(remoteMessage.data)) { @@ -383,9 +368,9 @@ if (MoEPushHelper.getInstance().isFromMoEngagePlatform(remoteMessage.data)) { } ``` -##### Push Registration and Receiving handled by SDK +##### Push registration and receiving handled by SDK -Add the below code in your manifest file. +Add the following code in your manifest file: ```xml @@ -397,7 +382,7 @@ Add the below code in your manifest file. When the MoEngage SDK handles push registration, it optionally provides a callback to the Application whenever a new token is registered or the token is refreshed. -An application can get this callback by implementing `FirebaseEventListener` and registering for a callback in the Application class `onCreate()` using `MoEFireBaseHelper.getInstance().addEventListener()` +An application can get this callback by implementing `FirebaseEventListener` and registering for a callback in the Application class `onCreate()` using `MoEFireBaseHelper.getInstance().addEventListener()`. Refer to the [MoEngage - API reference](https://moengage.github.io/android-api-reference-v11/moe-push-firebase/com.moengage.firebase.listener/-firebase-event-listener/index.html?query=open%20class%20FirebaseEventListener){:target="_blank"} for more details on the listener. @@ -405,22 +390,21 @@ Refer to the [MoEngage - API reference](https://moengage.github.io/android-api-r ##### Callbacks -Segment recommends that you add the callbacks in the onCreate() of the Application class since these callbacks can be triggered even when the application is in the background. +Segment recommends that you add the callbacks in the `onCreate()` of the application class since these callbacks can be triggered even when the application is in the background. -###### Token Callback +###### Token callback When MoEngage SDK handles push registration, it optionally provides a callback to the application whenever a new token is registered or the token is refreshed. To get the token callback implement the [TokenAvailableListener](https://moengage.github.io/android-api-reference/pushbase/com.moengage.pushbase.listener/-token-available-listener/index.html){:target="_blank"} and register for the callback using [MoEFireBaseHelper.getInstance().addTokenListener()](https://moengage.github.io/android-api-reference/moe-push-firebase/com.moengage.firebase/-mo-e-fire-base-helper/add-token-listener.html){:target="_blank"}. -###### Non-MoEngage Payload +###### Non-MoEngage payload If you're using the receiver provided by the SDK in your application's manifest file, SDK provides a callback in case a push payload is received for any other server apart from MoEngage Platform. To get a callback implement the [NonMoEngagePushListener](https://moengage.github.io/android-api-reference/moe-push-firebase/com.moengage.firebase.listener/-non-mo-engage-push-listener/index.html){:target="_blank"} and register for the callback using [MoEFireBaseHelper.getInstance().addNonMoEngagePushListener()](https://moengage.github.io/android-api-reference/moe-push-firebase/com.moengage.firebase/-mo-e-fire-base-helper/add-non-mo-engage-push-listener.html){:target="_blank"}. - -#### Declare and configure Rich Landing Activity: +#### Declare and configure rich landing activity: A rich landing page can be used to open a web URL inside the app through a push campaign. -The configuration below is only required if you want to add a parent activity to the Rich landing page. If not, you can move to the next section. +The following configuration is only required if you want to add a parent activity to the Rich landing page. If not, you can move to the next section. To use a rich landing page you need to add the below code in the AndroidManifest.xml Add the following snippet and replace `[PARENT_ACTIVITY_NAME]` with the name of the parent @@ -451,27 +435,25 @@ You are now all set up to receive push notifications from MoEngage. For more inf * [Release Notes](https://developers.moengage.com/hc/en-us/articles/4403896795540-Changelog){:target="_blank"} ### Identify -Use [Identify](/docs/connections/sources/catalog/libraries/mobile/android/#identify) to track user-specific attributes. This is the same as tracking [user attributes](https://developers.moengage.com/hc/en-us/articles/4402050979860-Track-User-Attributes){:target="_blank"} on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. If you set traits.id, MoEngage sets that as the Unique ID for that user. +Use [Identify](/docs/connections/sources/catalog/libraries/mobile/android/#identify) to track user-specific attributes. This is the same as tracking [user attributes](https://developers.moengage.com/hc/en-us/articles/4402050979860-Track-User-Attributes){:target="_blank"} on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. If you set `traits.id`, MoEngage sets that as the Unique ID for that user. > info "" > MoEngage supports anonymous identifiers in Device-mode only. If you use the MoEngage destination in Cloud-mode, use a known user identifier. ### Track -Use [track](/docs/connections/sources/catalog/libraries/mobile/android/#track) to track events and user behavior in your app. -This will send the event to MoEngage with the associated properties. Tracking events is essential and will help you create segments for engaging users. +Use [Track](/docs/connections/sources/catalog/libraries/mobile/android/#track) to track events and user behavior in your app. This sends the event to MoEngage with the associated properties. Tracking events is essential and helps you create segments for engaging users. ### Reset -If your app supports the ability for a user to logout and login with a new identity, then you'll need to call reset for the Analytics client. +If your app supports the ability for a user to logout and login with a new identity, then you need to call reset for the Analytics client. ### Sample Implementation -Refer to [this](https://github.com/moengage/moengage-segment-integration){:target="_blank"} GitHub repository for sample implementation +Refer to [MoEngage's](https://github.com/moengage/moengage-segment-integration){:target="_blank"} GitHub repository for sample implementation. ## Web The MoEngage WebSDK offers the ability to send push notifications to Google Chrome, Opera and Firefox browsers. Complete the following steps after you've configured Segment's `analytics.js.` - ### Integration #### 1. Setup your MoEngage Web SDK settings at MoEngage Dashboard @@ -483,15 +465,15 @@ If you have selected `HTTPS` mode of integration in the settings, complete the f #### 2 Set up for HTTPS websites #### 2.a Download the required files (HTTPS) -For HTTPS Web Push to work, you need to host two files in the `root` directory of your web server. These two files will be available for you to download at the [web settings page](https://app.moengage.com/v3/#/settings/push/web){:target="_blank"}. +For HTTPS Web Push to work, you need to host two files in the `root` directory of your web server. These two files are available for you to download at the [web settings page](https://app.moengage.com/v3/#/settings/push/web){:target="_blank"}. * `manifest.json` * `serviceworker.js` > info "Serviceworker file naming convention" -> The name of the serviceworker file must be `serviceworker.js`. Please contact MoEngage support at support@moengage.com if you want to give your serviceworker file a different name. +> The name of the serviceworker file must be `serviceworker.js`. Please contact [MoEngage support](mailto:support@moengage.com){:target="_blank"} if you want to give your serviceworker file a different name. #### 2.b Add link to manifest in HTML (HTTPS) -Add the following line in the tag of your page. +Add the following line in the `` tag of your page. ```html @@ -504,7 +486,7 @@ Add the following line in the tag of your page. #### 2.c Use your existing manifest or serviceworker file (HTTPS) If you already have these files, -1. **Manifest** - Add the sender ID you saved on MoEngage dashboard as the `gcm_sender_id`. If you've used `MoEngage Shared Project` while setting up, your sender id is `540868316921`. Edit your `manifest.json` as follows: +1. **Manifest** - Add the sender ID you saved on MoEngage dashboard as the `gcm_sender_id`. If you've used `MoEngage Shared Project` while setting up, your sender ID is `540868316921`. Edit your `manifest.json` as follows: ```json { ... @@ -513,7 +495,7 @@ If you already have these files, } ``` -2. **Service Worker** - Add the following line to the top of your `serviceworker.js` file +2. **Service Worker** - Add the following line to the top of your `serviceworker.js` file. ```js importScripts("//cdn.moengage.com/webpush/releases/serviceworker_cdn.min.latest.js?date="+ new Date().getUTCFullYear()+""+new Date().getUTCMonth()+""+new Date().getUTCDate()); @@ -523,84 +505,84 @@ If you already have these files, Use [Identify](/docs/sources/website/analytics.js/#identify) to track user specific attributes. This is equal to [tracking user attributes](https://developers.moengage.com/hc/en-us/articles/360061114832-Web-SDK-User-Attributes-Tracking){:target="_blank"} on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. > info "" -> MoEngage supports anonymous identifiers in Device-mode only. If you use the MoEngage destination in Cloud-mode, use a known user identifier. +> MoEngage supports anonymous identifiers in device-mode only. If you use the MoEngage destination in cloud-mode, use a known user identifier. ### Track -Use [track](/docs/sources/website/analytics.js/#track) to track events and user behavior in your app. This will send the event to MoEngage with the associated properties. Tracking events is essential and will help you create segments for engaging users. +Use [Track](/docs/sources/website/analytics.js/#track) to track events and user behavior in your app. This sends the event to MoEngage with the associated properties. Tracking events is essential and helps you create segments for engaging users. ### Reset -If your website supports the ability for a user to logout and login with a new identity, then you'll need to call [reset](/docs/sources/website/analytics.js/#reset-logout) method in `analytics.js`. +If your website supports the ability for a user to logout and login with a new identity, then you need to call [reset](/docs/sources/website/analytics.js/#reset-logout) method in `analytics.js`. -### Test Mode and Debugging +### Test mode and debugging While updating the MoEngage settings on the Segment Dashboard, you can enable the logging functionality of the MoEngage SDK to see the SDK logs on the browser console. Just set `Enable Debug Logging` to `On` and the SDK loads in debug mode. > success "" > When you enable debug mode, Segment sends the events and user attributes to the `TEST` environment of your MoEngage App. -## MoEngage Web SDK Features +## MoEngage Web SDK features For information about optional features, see the documentation below: -* [Configure opt in type](https://help.moengage.com/hc/en-us/articles/210224063-Configure-Web-Push-Settings#configure-web-push-opt-in-0-6){:target="_blank"} +* [Configure opt-in type](https://help.moengage.com/hc/en-us/articles/210224063-Configure-Web-Push-Settings#configure-web-push-opt-in-0-6){:target="_blank"} * [Self-handled opt-ins](https://developers.moengage.com/hc/en-us/articles/360061219351-Configure-Self-Handled-Opt-In){:target="_blank"} * [SDK callbacks](https://developers.moengage.com/hc/en-us/articles/4401950701076-Opted-Out-Users){:target="_blank"} -### On-Site Messaging +### On-Site messaging -On-site Messaging Campaigns allow you to show personalized pop-ups and non-intrusive banners on your website. +On-site messaging campaigns allow you to show personalized pop-ups and non-intrusive banners on your website. -Web SDK integration for On-site Messaging will automatically start working on all the pages where the web SDK is integrated. +Web SDK integration for On-site Messaging automatically starts working on all the pages where the web SDK is integrated. For more information, refer to [Configure and Integrate On-site Messaging](https://developers.moengage.com/hc/en-us/articles/360061573232-Configure-and-Integrate-On-site-Messaging){:target="_blank"}. -### Web Personalization +### Web personalization -Web Personalization is used to personalize the website experience for each user. A few popular use cases for Web Personalization include the home page banner personalization basis user behavior, localizing the website content basis user geography, testing the performance of new page layouts for improved performance, modifying the content shown on any webpage as per the user behavior. +Web personalization is used to personalize the website experience for each user. A few popular use cases for web personalization include the home page banner personalization basis user behavior, localizing the website content basis user geography, testing the performance of new page layouts for improved performance, modifying the content shown on any webpage as per the user behavior. -For more information, refer to [Configure and Integrate Web Personalization](https://developers.moengage.com/hc/en-us/articles/360062008891-Configure-and-Integrate-Web-Personlization){:target="_blank"}. +For more information, refer to MoEngage's documentation on how to [configure and integrate web personalization](https://developers.moengage.com/hc/en-us/articles/360062008891-Configure-and-Integrate-Web-Personlization){:target="_blank"}. ## Use Twilio Engage with MoEngage You can send [Computed traits](/docs/engage/audiences/computed-traits/) and [Audiences](/docs/audiences/audiences/) to MoEngage as custom attributes or custom events. -* Traits and audiences sent using the `identify` call will appear in MoEngage as _Tracked Custom Attributes_ with value as _True_. -* Traits and audiences sent using the `track` call will appear in MoEngage as _Tracked User Events_. +* Traits and audiences sent using the Identify call appear in MoEngage as _Tracked Custom Attributes_ with value as _True_. +* Traits and audiences sent using the Track call appear in MoEngage as _Tracked User Events_. -When connecting the calculated trait/audience to the MoEngage destination, you may select the method of your choice (or opt to utilise both). +When connecting the calculated trait or audience to the MoEngage destination, you can select the method of your choice (or opt to use both). -### Sync Time +### Sync yime -The default integration for MoEngage <> Twilio Engage connection is **Real Time.** But there are some filters that will disqualify the persona from syncing in real-time, including some time-based filters which restrict your audience’s size at the time of message send. +The default integration for MoEngage <> Twilio Engage connection is **Real Time.** But there are some filters that disqualify the persona from syncing in real-time, including some time-based filters which restrict your audience’s size at the time of message send. -### Computed Traits using Identify calls +### Computed traits using Identify calls -To generate custom attributes in MoEngage, you may provide Computed Traits defined in Engage as `Identify` calls. The Computed Trait's value is used to set the custom attribute. +To generate custom attributes in MoEngage, you may provide Computed Traits defined in Engage as Identify calls. The computed trait's value is used to set the custom attribute. ### Create a Segment Computed Trait -1. In Segment, navigate to the _Computed Traits_ in _Engage._ -2. Click _New Computed Trait_. +1. In Segment, navigate to the **Computed Traits** in Engage. +2. Click **New Computed Trait**. 3. Create your computed trait. A lightning bolt in the top corner of the page will indicate if the computation updates in real-time. - ![segment_new_trait.png](images/segment_new_trait.png) -4. Next, select _MoEngage_ as your destination. - ![segment_select_moengage_destination.png](images/segment_select_moengage_destination.png) -5. Preview by clicking _Review & Create_. - _Note-_ By default, Segment queries all historical data to set the current value of the computed trait and audience. To omit this data, uncheck _Historical Backfill_.  - ![segment_new_trait_backfill.png](images/segment_new_trait_backfill.png) + ![Screenshot of Configure and Preview Your Trait page](images/segment_new_trait.png) +4. Next, select **MoEngage** as your destination. + ![Screenshot of MoEngage (Actions) destination page in Segment](images/segment_select_moengage_destination.png) +5. Preview by clicking **Review & Create**. + > By default, Segment queries all historical data to set the current value of the computed trait and audience. To omit this data, uncheck **Historical Backfill**.  + ![Screenshot of Review & Create page with Historial Backfill section highlighted](images/segment_new_trait_backfill.png) 6. In the computed trait, adjust the connection settings based on how you would like your data sent to MoEngage. ### Create a Segment Audience -1. In Segment, navigate to the _Audience_ in _Engage_ -2. Click _New_. -3. Create your audience. A lightning bolt in the top corner of the page will indicate if the computation updates in real-time. - ![segment_audience_2.png](images/segment_audience_2.png) -4. Next, select _MoEngage_ as your destination. - ![segment_audience_destination.png](images/segment_audience_destination.png) -5. Preview your audience by clicking _Review & Create_. - _Note-_ By default, Segment queries all historical data to set the current value of the audience. To omit this data, uncheck _Historical Backfill_.  - ![segment_audience_4.png](images/segment_audience_4.png) +1. In Segment, navigate to the **Audience** in Engage. +2. Click **New**. +3. Create your audience. A lightning bolt indicates if the computation updates in real-time. + ![Screenshot Configure and Preview your Audience page](images/segment_audience_2.png) +4. Next, select **MoEngage** as your destination. + ![Screenshot of MoEngage (Actions) destination page in Segment](images/segment_audience_destination.png) +5. Preview your audience by clicking **Review & Create**. + > By default, Segment queries all historical data to set the current value of the audience. To omit this data, uncheck **Historical Backfill**.  + ![Screenshot of Review & Create page](images/segment_audience_4.png) 6. In the computed trait or audience settings, adjust the connection settings based on how you would like your data sent to MoEngage. - ![segment_audience_5.png](images/segment_audience_5.png) + ![Screenshot of Connection settings](images/segment_audience_5.png) ## Connect Twilio Engage to MoEngage @@ -612,9 +594,9 @@ First, link MoEngage to Twilio Engage to send Computed Traits or Audiences. The ## Segment users in MoEngage -To create a segment of these users, navigate to _Segments >> Create Segment._ Next, based on which call you used: +To create a segment of these users, navigate to **Segments > Create Segment**. Next, based on which call you used: -- **Identify**: Select _User Property_ and select the specific attribute. - ![moengage_segment_identify.png](images/moengage_segment_identify.png) -- **Track**: Select _User Behaviour_ and select the specific event. - ![moengage_segment_track.png](images/moengage_segment_track.png) +- **Identify**: Select **User Property** and select the specific attribute. + ![Screenshot of User property filter in MoEngage UI](images/moengage_segment_identify.png) +- **Track**: Select **User Behaviour** and select the specific event. + ![Screenshot of User behavior filter in MoEngage UI](images/moengage_segment_track.png) diff --git a/src/connections/destinations/catalog/olark/index.md b/src/connections/destinations/catalog/olark/index.md index cdc9587194..8e312ac787 100644 --- a/src/connections/destinations/catalog/olark/index.md +++ b/src/connections/destinations/catalog/olark/index.md @@ -2,35 +2,33 @@ title: Olark Destination id: 54521fd925e721e32a72eedc --- -## Getting Started +## Getting started -When you enable Olark in the Segment web app, your changes appear in the Segment CDN in about 45 minutes, and then Analytics.js starts asynchronously loading Olark's `loader0.js` onto your page. This means you should remove Olark's snippet from your page. -+ Olark's chat box will appear on your page, as configured in your [Olark account](http://www.olark.com/?r=qhl4tltg){:target="_blank"}, and you can start chatting with visitors. +When you enable Olark in the Segment Segmentb app, your changes appear in the Segment CDN in about 45 minutes. Analytics.js then starts asynchronously loading Olark's `loader0.js` onto your page. This means you should remove Olark's snippet from your page. -Olark is only supported in device mode (on the client). +Olark's chat box appears on your page, as configured in your [Olark account](http://www.olark.com/?r=qhl4tltg){:target="_blank"}, and you can start chatting with visitors. +Olark is only supported in device-mode (on the client). ## Page -When you call [`page`](/docs/connections/spec/page/), we call Olark's `sendNotificationToOperator` function as `looking at *url*`. You must enable this option with the *pageview* flag, because it can sometimes be bothersome. - +When you call [Page](/docs/connections/spec/page/), Segment calls Olark's `sendNotificationToOperator` function as `looking at *url*`. You must enable this option with the `pageview` flag, because it can sometimes be bothersome. ## Identify -When you call [`identify`](/docs/connections/spec/identify/) on `analytics.js`, we send the following data to Olark: +When you call [Identify](/docs/connections/spec/identify/) on `analytics.js`, Segment sends the following data to Olark: -* We call `api.chat.updateVisitorNickname` with `traits.name` and `traits.email`, or just their `traits.name` or just their `traits.email` or their `userId`. In that order of preference. -* We call `api.visitor.updateEmailAddress` with `traits.email` if you send it, or `userId` if that's an email. -* We call `api.visitor.updateFullName` with `traits.name` if you send it, or `traits.firstName` and `traits.lastName` appended with a space in between, if you send both first and last name. -* We call `api.visitor.updatePhoneNumber` with `traits.phone` if you send it. -* We call `api.visitor.updateCustomFields` with `traits`. +* Segment calls `api.chat.updateVisitorNickname` with `traits.name` and `traits.email`, or just their `traits.name` or just their `traits.email` or their `userId`. In that order of preference. +* Segment calls `api.visitor.updateEmailAddress` with `traits.email` if you send it, or `userId` if that's an email. +* Segment calls `api.visitor.updateFullName` with `traits.name` if you send it, or `traits.firstName` and `traits.lastName` appended with a space in betSegmenten, if you send both first and last name. +* Segment calls `api.visitor.updatePhoneNumber` with `traits.phone` if you send it. +* Segment calls `api.visitor.updateCustomFields` with `traits`. More documentation on the Olark API can be found [in Olark's docs](https://www.olark.com/api){:target="_blank"}. ## Track -When you call [`track`](/docs/connections/spec/track/) or one of its helpers on analytics.js, we call Olark's `sendNotificationToOperator` function as `visitor triggered *eventName*`. You must enable this option with the *track* flag, because it can sometimes be bothersome. - +When you call [Track](/docs/connections/spec/track/) or one of its helpers on analytics.js, Segment calls Olark's `sendNotificationToOperator` function as `visitor triggered *eventName*`. You must enable this option with the `track` flag. ## Features @@ -40,7 +38,7 @@ All the settings you can change [from your Olark settings pages](https://www.ola ### Olark JavaScript API -If you'd like to use the native Olark JavaScript functions after turning on Olark using Segment our `ready` function will allow you to do that. Since we still load the Olark library in the background you can access those functions like this: +If you'd like to use the native Olark JavaScript functions after turning on Olark using Segment, the `ready` function allows you to do that. Since Segment still loads the Olark library in the background, you can access those functions like this: ```js analytics.ready(function(){ @@ -48,20 +46,19 @@ analytics.ready(function(){ }); ``` -[Read the ready docs for more details](/docs/connections/sources/catalog/libraries/website/javascript/#ready) - +See the [`ready` docs](/docs/connections/sources/catalog/libraries/Segmentbsite/javascript/#ready) for more details. -## Record Live Chat Events +## Record Live Chat events -Using Olark through Segment gives you the ability to automatically record `track` events for live chat conversations. If you select this option, we'll collect the following events: +Using Olark through Segment gives you the ability to automatically record Track events for live chat conversations. If you select this option, Segment collects the following events: -* Live Chat Conversation Started -* Live Chat Message Sent -* Live Chat Message Received +* `Live Chat Conversation Started`. +* `Live Chat Message Sent`. +* `Live Chat Message Received`. -These events will be sent to other tools in your stack that can accept track calls, so you can do things like analyze if users who chat spend more money over time. +These events are sent to other tools in your stack that can accept Track calls, so you can do things like analyze if users who chat spend more money over time. -To learn more about the live chat events you can capture with this destination, head on over to our [Live Chat spec docs](/docs/connections/spec/live-chat/). +To learn more about the live chat events you can capture with this destination, see the [Live Chat spec docs](/docs/connections/spec/live-chat/). -![Turn on Olark](images/olarklivechat.png) +![Screenshot of Olark UI with option to Record live chat events highlighted](images/olarklivechat.png) diff --git a/src/connections/destinations/catalog/onesignal-new/index.md b/src/connections/destinations/catalog/onesignal-new/index.md index cc3f19ed19..5e761cdb3f 100644 --- a/src/connections/destinations/catalog/onesignal-new/index.md +++ b/src/connections/destinations/catalog/onesignal-new/index.md @@ -6,32 +6,29 @@ redirect_from: '/connections/destinations/catalog/onesignal/' id: 60b6a5b69fec493efbd3c64c --- [OneSignal](https://onesignal.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank"} is the market leader in driving customer engagement with multi-channel messaging across Web and Mobile Push, In-App Messages, SMS, and Email subscribers. -This destination is maintained by OneSignal. For any issues with the destination, [contact the OneSignal Support team](mailto:support@onesignal.com). -> info "" -> The OneSignal Destination is available to customers on OneSignal Growth, Professional and Enterprise plans. - -## Getting Started +This destination is maintained by OneSignal. For any issues with the destination, [contact the OneSignal support team](mailto:support@onesignal.com){:target="_blank"}. +> info "" +> The OneSignal Destination is available to customers on OneSignal Growth, Professional, and Enterprise plans. +## Getting started -1. Log in to the [OneSignal Dashboard](https://app.onesignal.com/){:target="_new"} -2. Navigate to **Segment App** -> **Settings** -> **Analytics** -> **Segment.com** and click **Activate**. +1. Log in to the [OneSignal dashboard](https://app.onesignal.com/){:target="_blank"}. +2. Navigate to **Segment App > Settings > Analytics > Segment.com** and click **Activate**. 3. The Segment App opens in a new window. Log in to authenticate the connection from OneSignal. -4. Select the Workspace and Source to connect with OneSignal. - +4. Select the workspace and source to connect with OneSignal. > info "" > OneSignal maps the `userId` field to the **[External User ID](https://documentation.onesignal.com/docs/onboarding-with-onesignal#step-3-connect-user-data-to-onesignal){:target="_blank"}** field in OneSignal. - ## Supported methods OneSignal supports the following methods, as specified in the [Segment Spec](/docs/connections/spec). ### Identify -Send [Identify](/docs/connections/spec/identify) calls to update Users. For example: +Send [Identify](/docs/connections/spec/identify) calls to update users. For example: ```js analytics.identify('userId123', { @@ -62,25 +59,25 @@ analytics.track('Add to Cart', { }) ``` -OneSignal stores Track properties as Data Tags but drops the event name. In the above example, `Add to Cart` is dropped. +OneSignal stores Track properties as Data Tags but drops the event name. In the example, `Add to Cart` is dropped. To keep the event names on OneSignal Data Tags, append the event name to the properties. For example, `Add_to_Cart_brand` instead of `brand`. -![""](images/track-example.png) +![Screenshot of the OneSignal dashboard showing a notification for an "eShoppe" campaign.](images/track-example.png) ## Engage -Send Computed Traits and Audiences generated using [Engage](/docs/engage) to OneSignal +You can send Computed Traits and Audiences generated using [Engage](/docs/engage) to OneSignal. ### Audiences -Engage Audiences appear as a [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} in OneSignal. +Engage audiences appear as a [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} in OneSignal. -Track calls from Audiences create a OneSignal [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} with the Audience Name. +Track calls from Audiences create a OneSignal [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} with the audience name. -Identify calls from Audiences create a OneSignal [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} with the Audience Name and add Data Tags on all the matching user records. +Identify calls from Audiences create a OneSignal [segment](https://documentation.onesignal.com/docs/segmentation){:target="_blank"} with the audience name and add Data Tags on all the matching user records. -![""](images/audiences.jpg) +![Screenshot of the OneSignal "eShoppe" dashboard](images/audiences.jpg) Audiences sends Identify and Track calls to OneSignal when a user enters or exits the Audience. @@ -88,13 +85,11 @@ Audiences sends Identify and Track calls to OneSignal when a user enters or exit OneSignal stores Track and Identify calls from Engage Computed Traits as [Data Tags](https://documentation.onesignal.com/docs/add-user-data-tags){:target="_blank"} for the OneSignal User/Player's records. -## OneSignal Destination FAQ -### Managing Segment's Reserved and Custom Traits - -* Segment sends user traits to OneSignal as Data Tags. The number of data tags OneSignal allows depends on your OneSignal pricing plan. OneSignal drops the data tags that go over your set number. . - -* OneSignal always updates the `firstName` and the `lastName` properties for matching users. All other traits are added/updated on a first-come basis. `firstName` and `lastName` tags are stored as `first_name` and `last_name`. +## FAQ -* Send User properties to OneSignal with blank/null values to remove the corresponding Data Tag from the OneSignal user record. +#### How do I manage Segment's Reserved and Custom Traits? +* Segment sends user traits to OneSignal as Data Tags. The number of data tags OneSignal allows depends on your OneSignal pricing plan. OneSignal drops the data tags that go over your set number. +* OneSignal always updates the `firstName` and the `lastName` properties for matching users. All other traits are added or updated on a first-come basis. `firstName` and `lastName` tags are stored as `first_name` and `last_name`. +* Send User properties to OneSignal with blank or `null` values to remove the corresponding Data Tag from the OneSignal user record. * OneSignal doesn't store `email` and `phone` properties. To update `email` and `phone` properties in OneSignal, create a player record with the email address and/or a phone number and map those records with the External_User_ID. Additional properties from Segment map across all your matching records, including email and phone number records. diff --git a/src/connections/destinations/catalog/optimizely-full-stack/index.md b/src/connections/destinations/catalog/optimizely-full-stack/index.md index 83ce88bc18..2171659fe6 100644 --- a/src/connections/destinations/catalog/optimizely-full-stack/index.md +++ b/src/connections/destinations/catalog/optimizely-full-stack/index.md @@ -4,167 +4,164 @@ hide-personas-partial: true redirect_from: '/connections/destinations/catalog/optimizelyx/' id: 59d3b44b8f1480000104be6b --- -## Getting Started +## Getting started +Segment's Optimizely Full Stack destination, previously Optimizely X, supports the following Optimizely products: - -Segment's **Optimizely Full Stack (previously Optimizely X)** destination supports the following Optimizely products: - -* [Optimizely Full Stack (server)](#server-side) -* [Optimizely Full Stack Android (Cloud-mode)](#android-cloud-mode-implementation) -* [Optimizely Full Stack iOS (Cloud-mode)](#ios-cloud-mode-implementation) +* [Optimizely Full Stack (server)](#server-side). +* [Optimizely Full Stack Android (Cloud-mode)](#android-cloud-mode-implementation). +* [Optimizely Full Stack iOS (Cloud-mode)](#ios-cloud-mode-implementation). If you're interested in implementing Optimizely X Web or Optimizely Full Stack with the JavaScript SDK, see Segment's [**Optimizely Web Destination**](/docs/connections/destinations/catalog/optimizely-web/), or follow the links below: -* [Optimizely X Web](/docs/connections/destinations/catalog/optimizely/#optimizely-x-web) -* [Optimizely Full Stack (JavaScript SDK)](/docs/connections/destinations/catalog/optimizely-web/#optimizely-full-stack-javascript-sdk) +* [Optimizely X Web](/docs/connections/destinations/catalog/optimizely/#optimizely-x-web). +* [Optimizely Full Stack (JavaScript SDK)](/docs/connections/destinations/catalog/optimizely-web/#optimizely-full-stack-javascript-sdk). -## Implementation Prerequisite +## Implementation prerequisite -Optimizely works differently than other Segment destinations: It requires that customers implement some Optimizely functionality natively to make sure your experiment logic runs correctly. +Optimizely works differently than other Segment destinations. It requires that customers implement some Optimizely functionality natively to make sure the experiment logic runs correctly. -Segment maps `track` events to Optimizely's `track` method, customers must implement all Optimizely decision-based methods, such as `activate` and `isFeatureEnabled` natively. Segment's API does not include methods that correspond to decision-based methods. +Segment maps Track events to Optimizely's `track` method, customers must implement all Optimizely decision-based methods, such as `activate` and `isFeatureEnabled` natively. Segment's API doesn't include methods that correspond to decision-based methods. This requires that customers include a native Optimizely implementation before their Segment implementation on pages or in mobile apps where Optimizely experiments run. -## Server Side +## Server-side -### Getting Started +### Getting started -1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (*not the "Optimizely Web" destination*). +1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (**not the "Optimizely Web" destination**). 2. Include your Optimizely project's `datafile` URL in your Segment settings. 3. Create a native Optimizely instance in your server environment so you can access Optimizely decisioning methods like `activate`, `isFeatureEnabled`. -4. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and to associate `metrics` with the appropriate Optimizely Experiments. Segment maps `track` event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps `track` event `context.traits` to Optimizely `attributes`. +4. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and to associate `metrics` with the appropriate Optimizely Experiments. Segment maps Track event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps Track event `context.traits` to Optimizely `attributes`. > warning "Optimizely SDKs v1.x or v2.x require matching `attributes` objects for correct attribution" -> If you use Optimizely SDKs v1.x or v2.x and use any `activate` or `isFeatureEnabled` calls, the `attributes` object for each user must match the `attributes` object passed to any `track` calls for that user id so that it can be correctly attributed on the Optimizely results page. +> If you use Optimizely SDKs v1.x or v2.x and use any `activate` or `isFeatureEnabled` calls, the `attributes` object for each user must match the `attributes` object passed to any Track calls for that user ID so that it can be correctly attributed on the Optimizely results page. -If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user id stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment `track` calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the `track` calls for that user id. +If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user ID stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment Track calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the Track calls for that user id. -For more details on how events are attributed on the Optimizely results page, refer to their documentation [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. +For more details on how events are attributed on the Optimizely results page, refer to Optimizely's documentation on [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. ### Track -Upon invocation of a Segment `track` event, Segment maps the event to an Optimizely `track` event: -* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard; -* If the experiment `metric` is associated with a running experiment; -* If the current user has been assigned a `userId` using Segment's `identify` method (for example, `analytics.identify('123')`); +Upon invocation of a Segment Track event, Segment maps the event to an Optimizely `track` event: +* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard. +* If the experiment `metric` is associated with a running experiment. +* If the current user has been assigned a `userId` using Segment's Identify method (for example, `analytics.identify('123')`). * If the current user is activated in a running experiment with the associated `metric`. Segment also handles the following mapping: -* Segment `track` event name to Optimizely `eventName`. -* Segment `track` event `properties` to Optimizely `eventTags`. -* Segment `track` event `context.traits` to Optimizely `attributes`. +* Segment Track event name to Optimizely `eventName`. +* Segment Track event `properties` to Optimizely `eventTags`. +* Segment Track event `context.traits` to Optimizely `attributes`. -`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by `100`. +`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents. For example, $1 should be represented by `100`. > info "Custom Event Tags are not displayed on the Optimizely results page" > Optimizely's [Custom Event Tags](https://docs.developers.optimizely.com/full-stack/docs/include-event-tags){:target="_blank"}, which include all Event Tags except `revenue` and `value`, are not displayed on the Optimizely results page. However, these tags are available in a [Data Export](https://docs.developers.optimizely.com/web/docs/data-export){:target="_blank"} report. Event Tags can be strings, integers, floating point numbers, or boolean values. Optimizely rejects events with any other data types (for example, arrays). -Segment defaults to identifying users with their `anonymousId`. Enabling the "Use User ID" setting in your Segment settings means that only `track` events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. +Segment defaults to identifying users with their `anonymousId`. Enabling the **Use User ID** setting in your Segment settings means that only Track events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. -### Notification Listeners +### Notification listeners -Segment's server-side integration with Optimizely Full Stack does not support notification listeners for Segment`track` events. [Notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"} are still available with any native call invoked from your Optimizely client instance. +Segment's server-side integration with Optimizely Full Stack does not support notification listeners for SegmentTrack events. [Notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"} are still available with any native call invoked from your Optimizely client instance. -## Android Cloud-mode Implementation +## Android cloud-mode implementation -### Getting Started +### Getting started -1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (*not the "Optimizely Web" destination*). +1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (**not the "Optimizely Web" destination**). 2. Include the latest version of Optimizely Full Stack's native SDK in your your app-level build.gradle file and [implement Optimizely as your would natively](https://docs.developers.optimizely.com/full-stack/docs/install-the-sdk#section-android){:target="_blank"}. -3. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and associate `metrics` with the appropriate Optimizely Experiments. Segment maps `track` event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps `identify` `traits` to Optimizely `attributes`. +3. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and associate `metrics` with the appropriate Optimizely Experiments. Segment maps Track event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps Identify `traits` to Optimizely `attributes`. -When implementing Optimizely Full Stack using cloud-mode, Segment will map `track` events to Optimizely `track` events on our servers and deliver the data to your Optimizely project as usual. +When implementing Optimizely Full Stack using cloud-mode, Segment maps Track events to Optimizely Track events on our servers and deliver the data to your Optimizely project as usual. > warning "Optimizely SDKs v1.x or v2.x require matching `attributes` objects for correct attribution" -> If you use Optimizely SDKs v1.x or v2.x and use any `activate` or `isFeatureEnabled` calls, the `attributes` object for each user must match the `attributes` object passed to any `track` calls for that user id so that it can be correctly attributed on the Optimizely results page. +> If you use Optimizely SDKs v1.x or v2.x and use any `activate` or `isFeatureEnabled` calls, the `attributes` object for each user must match the `attributes` object passed to any Track calls for that user id so that it can be correctly attributed on the Optimizely results page. -If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user id stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment `track` calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the `track` calls for that user id. +If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user id stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment Track calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the Track calls for that user id. -For more details on how events are attributed on the Optimizely results page, refer to their documentation [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. +For more details on how events are attributed on the Optimizely results page, refer to Optimizely's documentation on [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. ### Track -Upon invocation of a Segment `track` event, Segment maps the event to an Optimizely `track` event: -* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard; -* If the experiment `metric` is associated with a running experiment; +Upon invocation of a Segment Track event, Segment maps the event to an Optimizely Track event: +* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard. +* If the experiment `metric` is associated with a running experiment. * If the current user is activated in a running experiment with the associated `metric`. Segment also handles the following mapping: -* Segment `track` event name to Optimizely `eventName`. -* Segment `track` event `properties` to Optimizely `eventTags`. +* Segment Track event name to Optimizely `eventName`. +* Segment Track event `properties` to Optimizely `eventTags`. -`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by `100`. +`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents. For example, $1 should be represented by `100`. > info "Custom Event Tags are not displayed on the Optimizely results page" > Optimizely's [Custom Event Tags](https://docs.developers.optimizely.com/full-stack/docs/include-event-tags){:target="_blank"}, which include all Event Tags except `revenue` and `value`, are not displayed on the Optimizely results page. However, these tags are available in a [Data Export](https://docs.developers.optimizely.com/web/docs/data-export){:target="_blank"} report. Event Tags can be strings, integers, floating point numbers, or boolean values. Optimizely rejects events with any other data types (for example, arrays). -Segment defaults to identifying users with their `anonymousId`. Enabling "Use User ID" setting in your Segment dashboard means that only `track` events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. +Segment defaults to identifying users with their `anonymousId`. Enabling the **Use User ID** setting in your Segment dashboard means that only Track events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. ### Identify -Invoking a Segment `identify` event sets Segment `traits` as Optimizely `attributes`. The `attributes` are sent downstream to Optimizely upon invocation of the next Segment `track` event. +Invoking a Segment Identify event sets Segment `traits` as Optimizely `attributes`. The `attributes` are sent downstream to Optimizely upon invocation of the next Segment Track event. ## Reset Invoking this method invalidates the listener for the `Experiment Viewed` event. -### Notification Listeners +### Notification listeners -If you want to use Optimizely's [notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"}, you must use the Optimizely native code to invoke them (in addition to using the Segment SDKs). Notification listeners require an [instantiated Optimizely client](https://docs.developers.optimizely.com/full-stack/docs/java#section-2-instantiate-optimizely){:target="_blank"} to be accessed, and so are not available for Segment `track` events when you connect to Optimizely using cloud-mode. +If you want to use Optimizely's [notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"}, you must use the Optimizely native code to invoke them (in addition to using the Segment SDKs). Notification listeners require an [instantiated Optimizely client](https://docs.developers.optimizely.com/full-stack/docs/java#section-2-instantiate-optimizely){:target="_blank"} to be accessed, and so are not available for Segment Track events when you connect to Optimizely using cloud-mode. +## iOS cloud-mode implementation -## iOS Cloud-mode Implementation +### Getting started -### Getting Started - -1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (*not the "Optimizely Web" destination*). +1. In your Segment source dashboard, enable the "Optimizely Full Stack" destination (**not the "Optimizely Web" destination**). 2. Include the latest version of Optimizely Full Stack's native SDK in your app and [implement it as you would natively](https://docs.developers.optimizely.com/full-stack/docs/install-the-sdk#section-ios-and-tvos){:target="_blank"}. -3. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and to associate `metrics` with the appropriate Optimizely Experiments. Segment maps `track` event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps `identify` `traits` to Optimizely `attributes`. +3. Finally, define any [`events`](https://docs.developers.optimizely.com/full-stack/docs/create-events){:target="_blank"} and [`attributes`](https://docs.developers.optimizely.com/full-stack/docs/define-attributes){:target="_blank"} in your Optimizely dashboard, and to associate `metrics` with the appropriate Optimizely Experiments. Segment maps Track event names to Optimizely `eventName` - the `eventName` corresponds to an experiment `metric`. In addition, Segment maps Identify `traits` to Optimizely `attributes`. -When implementing Optimizely using cloud-mode, Segment will map `track` events to Optimizely `track` events on our servers and deliver the data to your Optimizely project as usual. +When implementing Optimizely using cloud-mode, Segment mapS Track events to Optimizely Track events on our servers and deliver the data to your Optimizely project as usual. -> warning "Optimizely SDKs v1.x or v2.x require matching `attributes` objects for correct attribution" +> warning "Optimizely SDKs v1.x or v2.x require matching attributes objects for correct attribution" > If you use Optimizely SDKs v1.x or v2.x and use any `activate` or `isFeatureEnabled` calls, the `attributes` object for each user must match the `attributes` object passed to any Track calls for that user id so that it can be correctly attributed on the Optimizely results page. -If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user id stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment `track` calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the `track` calls for that user id. +If you are using Optimizely SDKs v3+, [Easy Event Tracking](https://blog.optimizely.com/2019/02/26/introducing-easy-event-tracking-the-easier-way-to-understand-and-optimize-the-customer-journey/){:target="_blank"} is enabled by default for decision events. Set up does not require maintaining the attributes of a user as long as the user id stays the same between Optimizely `activate` and `isFeatureEnabled` calls and Segment Track calls to have Optimizely `metrics` populated in the Optimizely results page. If you would like to segment your Optimizely results by user `attribute`, then make sure the `attributes` passed in for the `activate` and `isFeatureEnabled` calls match the `attributes` passed in for the Track calls for that user id. -For more details on how events are attributed on the Optimizely results page, refer to their documentation [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. +For more details on how events are attributed on the Optimizely results page, refer to Optimizely's documentation on [How Optimzely Experimentation counts conversions](https://support.optimizely.com/hc/en-us/articles/19888476989325-How-Optimizely-Experimentation-counts-conversions){:target="_blank"}. ### Track -Upon invocation of a Segment `track` event, Segment maps the event to an Optimizely `track` event: -* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard; -* If the experiment `metric` is associated with a running experiment; +Upon invocation of a Segment Track event, Segment maps the event to an Optimizely Track event: +* If the Segment event name matches exactly the name of an active experiment `metric` set up in the Optimizely dashboard. +* If the experiment `metric` is associated with a running experiment. * If the current user is activated in a running experiment with the associated `metric`. Segment also handles the following mapping: -* Segment `track` event name to Optimizely `eventName`. -* Segment `track` event `properties` to Optimizely `eventTags`. +* Segment Track event name to Optimizely `eventName`. +* Segment Track event `properties` to Optimizely `eventTags`. -`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by `100`. +`revenue` values should be passed as a Segment `property`. The value should be an integer and represent the value in cents. For example, $1 should be represented by `100`. > info "Custom Event Tags are not displayed on the Optimizely results page" > Optimizely's [Custom Event Tags](https://docs.developers.optimizely.com/full-stack/docs/include-event-tags){:target="_blank"}, which include all Event Tags except `revenue` and `value`, are not displayed on the Optimizely results page. However, these tags are available in a [Data Export](https://docs.developers.optimizely.com/web/docs/data-export){:target="_blank"} report. Event Tags can be strings, integers, floating point numbers, or boolean values. Optimizely rejects events with any other data types (for example, arrays). -Segment defaults to identifying users with their `anonymousId`. Enabling "Use User ID" setting in your Segment dashboard means that only `track` events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. +Segment defaults to identifying users with their `anonymousId`. Enabling the **Use User ID** setting in your Segment dashboard means that only Track events triggered by identified users are passed downstream to Optimizely. You may optionally fall back to `anonymousId` when `userId` is unavailable by setting `fallbackToAnonymousId` to `true`. ### Identify -Invoking a Segment `identify` event sets Segment `traits` as Optimizely `attributes`. The `attributes` are sent downstream to Optimizely upon invocation of the next Segment `track` event. +Invoking a Segment Identify event sets Segment `traits` as Optimizely `attributes`. The `attributes` are sent downstream to Optimizely upon invocation of the next Segment Track event. -### Notification Listeners +### Notification listeners -Notification listeners are not available for Segment `track` events when implementing Optimizely using Segment using cloud-mode. [Notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"} are still available with any native call invoked from your Optimizely client instance. +Notification listeners are not available for Segment Track events when implementing Optimizely using Segment using cloud-mode. [Notification listeners](https://docs.developers.optimizely.com/full-stack/docs/notification-listeners){:target="_blank"} are still available with any native call invoked from your Optimizely client instance. ## Engage Follow these instructions on how to set up Engage and Optimizely: -* [Using Segment Personas and Optimizely Full Stack for Omnichannel Experiments](https://www.optimizely.com/insights/blog/segment-personas-optimizely-full-stack-omnichannel-experiments/){:target="_blank"} +* [Using Segment Personas and Optimizely Full Stack for Omnichannel Experiments](https://www.optimizely.com/insights/blog/segment-personas-optimizely-full-stack-omnichannel-experiments/){:target="_blank"}. -## GDPR Support -Segment supports deleting/suppressing users in Optimizely using the [Segment app](/docs/privacy/user-deletion-and-suppression/). In order to do this however, you will need to create a [Personal Access Token](https://developers.optimizely.com/x/authentication/personal-token/){:target="_blank"} in Optimizely and provide it as the value of the Access Token setting. +## GDPR support +Segment supports deleting or rsuppressing users in Optimizely using the [Segment app](/docs/privacy/user-deletion-and-suppression/). In order to do this however, you need to create a [Personal Access Token](https://developers.optimizely.com/x/authentication/personal-token/){:target="_blank"} in Optimizely and provide it as the value of the Access Token setting. diff --git a/src/connections/destinations/catalog/pendo/index.md b/src/connections/destinations/catalog/pendo/index.md index 7d6f0f35f7..5ed5e8ac11 100644 --- a/src/connections/destinations/catalog/pendo/index.md +++ b/src/connections/destinations/catalog/pendo/index.md @@ -5,36 +5,34 @@ id: 575ef2fc80412f644ff139be --- [Pendo](http://www.pendo.io/){:target="_blank"} is a product cloud that helps product teams deliver software users love. With Pendo, product teams can understand product usage, collect feedback, measure NPS, onboard users, and announce new features in app—all without requiring engineering resources. -Pendo maintains this destination. For any issues with the destination, [contact the Pendo Support team](https://support.pendo.io/hc/en-us/articles/360034163971){:target="_blank"}. - -## Getting Started - +Pendo maintains this destination. For any issues with the destination, [contact the Pendo support team](https://support.pendo.io/hc/en-us/articles/360034163971){:target="_blank"}. +## Getting started 1. From the Segment web app, click **Catalog**. 2. Search for "Pendo" in the Catalog, select it, and choose which of your sources to connect the destination to. -3. In the destination settings, enter your Pendo API Key which a Pendo admin can find in the Pendo UI by going to Settings > [Subscription Settings](https://app.pendo.io/admin){:target="_blank"} > Applications, opening the relevant app, then locating the **API key** value. +3. In the destination settings, enter your Pendo API Key. To find the key in the Pendo UI as a Pendo admin, go to **Settings > [Subscription Settings](https://app.pendo.io/admin){:target="_blank"} > Applications**, open the relevant app, then locate the **API key** value. Your changes appear in the Segment CDN in about 45 minutes, and then Analytics.js starts asynchronously loading Pendo's snippet on your page and sending data. - This pulls in all page and click events without needing to make additional method calls. +This pulls in all page and click events without needing to make additional method calls. ### Cloud-mode configuration -> info "" -> The Pendo destination does not natively support Cloud-mode connections. Use the [Webhook](/docs/connections/destinations/catalog/webhooks) destination to send data to Pendo using a Cloud-mode connection. +> info "Pendo does not natively support cloud-mode connections" +> The Pendo destination does not natively support cloud-mode connections. Use the [webhook](/docs/connections/destinations/catalog/webhooks) destination to send data to Pendo using a cloud-mode connection. -To add the Pendo destination using Cloud-mode, use the [Webhooks](/docs/connections/destinations/catalog/webhooks) destination to enable Segment to send data to Pendo through a webhook. +To add the Pendo destination using cloud-mode, use the [webhooks](/docs/connections/destinations/catalog/webhooks) destination to enable Segment to send data to Pendo through a webhook. 1. From the Segment web app, click **Catalog**. 2. Search for **Webhooks** in the Catalog, select it, and choose which of your JavaScript sources to connect the destination to. -3. Webhook URL configuration will vary based on which Pendo environment you use and your API key: - * For US customers, add the following as your Webhook URL: `https://data.pendo.io/data/segmentio/YOUR_PENDO_API_KEY` and replace `YOUR_PENDO_API_KEY` with your actual Pendo API Key, which a Pendo Admin can find in the Pendo UI by going to **Settings** > [Subscription Settings](https://app.pendo.io/admin){:target="_blank"} > **Applications**, opening the relevant app, then locating the **API key** value. - * For EU customers, add the following as your Webhook URL: `https://data.eu.pendo.io/data/segmentio/YOUR_PENDO_API_KEY` and replace `YOUR_PENDO_API_KEY` with your actual Pendo API Key, which a Pendo Admin can find in the Pendo UI by going to **Settings** > [Subscription Settings](https://app.eu.pendo.io/admin){:target="_blank"} > **Applications**, opening the relevant app, then locating the **API Key** value. +3. Webhook URL configuration varies based on which Pendo environment you use and your API key: + * For US customers, add the following as your Webhook URL: `https://data.pendo.io/data/segmentio/YOUR_PENDO_API_KEY` and replace `YOUR_PENDO_API_KEY` with your actual Pendo API Key. + * For EU customers, add the following as your Webhook URL: `https://data.eu.pendo.io/data/segmentio/YOUR_PENDO_API_KEY` and replace `YOUR_PENDO_API_KEY` with your actual Pendo API Key. 4. Headers are not required in Webhook configuration. Once you're done adding in your URL, save changes. -5. Using the `track` method requires a setting enabled on your Pendo subscription (cloud-mode only). Contact Pendo to enable this feature flag for your account. +5. Using the [Track method](/docs/connections/spec/track/) requires a setting enabled on your Pendo subscription (cloud-mode only). Contact Pendo to enable this feature flag for your account. -To learn more about server-side data to Pendo, see Pendo's [support documentation](https://support.pendo.io/hc/en-us/articles/360031870352){:target = "_blank"}. +To learn more about server-side data to Pendo, see Pendo's [support documentation](https://support.pendo.io/hc/en-us/articles/360031870352){:target="_blank"}. ## Identify diff --git a/src/connections/destinations/catalog/planhat/index.md b/src/connections/destinations/catalog/planhat/index.md index 6bb2324655..08cb3c80a4 100644 --- a/src/connections/destinations/catalog/planhat/index.md +++ b/src/connections/destinations/catalog/planhat/index.md @@ -2,27 +2,25 @@ title: Planhat Destination id: 55bbefd70a20f4e22f0fb3e5 --- -## Getting Started +## Getting started -Getting data from Segment to Planhat's [Customer Success Tool](http://www.planhat.com/){:target="_blank"} is easy. +You can get data from Segment to Planhat's [Customer Success Tool](http://www.planhat.com/){:target="_blank"} following these steps: +1. Once the Segment library is integrated with your product, toggle Planhat on in your Segment destinations. +2. Add your Planhat API Key which you can generate in Planhat under **App Settings > API Access**. -Once the Segment library is integrated with your product, toggle Planhat on in your Segment destinations, and add your Planhat API Key which you can generate in Planhat under App Settings > API Access. - -The Segment Planhat destination is 100% handled through our servers, so you don't need to bundle their iOS or Android SDKs. Your Segment SDK will be enough. - -The Segment Planhat destination supports Identify, Page, Track, and Group calls. For more information, see the [Segment Spec documentation](/docs/connections/spec/). +The Segment-Planhat destination is 100% handled through the Segment servers, so you don't need to bundle their iOS or Android SDKs. Your Segment SDK is enough. +The destination also supports Identify, Page, Track, and Group calls. For more information, see the [Segment Spec documentation](/docs/connections/spec/). ## Identify -When you `identify` a user, we'll pass that user's information to Planhat with `userId` as Planhat's External User ID. Segment's special traits recognized as Planhat's standard contact profile fields (in parentheses) are: - -- `name` (`name`) -- `title` (`title`) -- `email` (`email`) -- `user_id` (`externalId`) +When you Identify a user, the user's information is passed on to Planhat with `userId` as Planhat's External User ID. Segment's special traits recognized as Planhat's standard contact profile fields (in parentheses) are: +- `name` (`name`). +- `title` (`title`). +- `email` (`email`). +- `user_id` (`externalId`). -In addition, all calls will get Segment as 'source'. +In addition, all calls get Segment as 'source'. -If the `userId` or `traits.email` matches an existing Contact in Planhat the Identify-call will automatically be associated with that Contact. Otherwise a new Contact will be created in Planhat. New Contacts received from Segment can either be discarded or manually assigned to a Customer profile in Planhat. +If the `userId` or `traits.email` matches an existing Contact in Planhat the Identify-call is automatically associated with that Contact. Otherwise a new Contact is created in Planhat. New Contacts received from Segment can either be discarded or manually assigned to a Customer profile in Planhat. diff --git a/src/connections/destinations/catalog/posthog/index.md b/src/connections/destinations/catalog/posthog/index.md index d4fa611dd3..07fa921e84 100644 --- a/src/connections/destinations/catalog/posthog/index.md +++ b/src/connections/destinations/catalog/posthog/index.md @@ -11,15 +11,15 @@ This destination is maintained by PostHog. For any issues with the destination, ## Getting started -1. From the Destinations catalog page in the Segment App, click **Add Destination**. +1. From the destinations catalog page in the Segment App, click **Add Destination**. 2. Search for "PostHog" in the Destinations Catalog, and select the PostHog destination. -3. Choose which Source should send data to the PostHog destination. +3. Choose which source should send data to the PostHog destination. 4. Go to your [PostHog project settings](https://us.posthog.com/settings/project#variables){:target="_blank"}, and copy the **project API key**. 5. Enter the project API Key that you copied in the PostHog destination settings in Segment. -6. Enter your PostHog instance address *without any trailing slash*, for example: - - `https://us.i.posthog.com` if you use PostHog US Cloud - - `https://eu.i.posthog.com` if you use PostHog EU Cloud - - Your self-hosted URL if you self-host +6. Enter your PostHog instance address **without any trailing slash**, for example: + - `https://us.i.posthog.com` if you use PostHog US Cloud. + - `https://eu.i.posthog.com` if you use PostHog EU Cloud. + - Your self-hosted URL if you self-host. ## Page @@ -36,7 +36,7 @@ Segment sends Page calls to PostHog as a `$pageview`. If you aren't familiar with the Segment Spec, take a look at the [Screen method documentation](/docs/connections/spec/screen/) to learn about what it does. An example call would look like: -```obj +```objc [[SEGAnalytics sharedAnalytics] screen:@"Home"]; ``` diff --git a/src/connections/destinations/catalog/preact/index.md b/src/connections/destinations/catalog/preact/index.md index d14b58d3eb..abcafd81ef 100644 --- a/src/connections/destinations/catalog/preact/index.md +++ b/src/connections/destinations/catalog/preact/index.md @@ -1,31 +1,31 @@ --- title: Preact Destination +hidden: true --- ## Identify -To create users in in Preact you'll use our [`identify`](/docs/connections/spec/identify) method. Users must be identified on the client side for events to appear in Preact. +To create users in in Preact, use the [Identify](/docs/connections/spec/identify) method. Users must be identified on the client side for events to appear in Preact. ## Group -To group users into accounts in preact you'll use our [`group`](/docs/connections/spec/group) method. +To group users into accounts in Preact, use the [Group](/docs/connections/spec/group) method. ## Track -Our [`track`](/docs/connections/spec/track) method will record events in Preact. Users must be identified on the client side for events to appear in Preact. - +The [Track](/docs/connections/spec/track) method records events in Preact. Users must be identified on the client side for events to appear in Preact. ## Features -### Recording Errors +### Recording errors -Preact can be really useful for customer support. For that to work well you'll want to send error events to Preact. +Preact can be useful for customer support. For that to work, you can send error events to Preact. -All you have to do is add a "!" as the first character in the event name and Preact will recognize it as an error event. Properties sent with the event will also show up in Preact. +Add a "!" as the first character in the event name and Preact recognizes it as an error event. Properties sent with the event also show up in Preact. Here's a JavaScript example: ```javascript