Merge pull request #1026 from segmentio/irina-facebbook-ldu

docs for new LDU feature

Author: n2parko

src/_data/sidenav/strat.yml

@@ -21,8 +21,12 @@ sections:
   section:
   - path: /connections/destinations/catalog/facebook-pixel
     title: Facebook Pixel destination
+  - path: /connections/destinations/catalog/facebook-pixel-server-side
+    title: Facebook Pixel Server destination (Beta)
   - path: /connections/destinations/catalog/facebook-app-events
     title: Facebook App Events destination
+  - path: /connections/destinations/catalog/facebook-offline-conversions
+    title: Facebook Offline Conversions destination
   - path: /connections/sources/catalog/cloud-apps/facebook-ads
     title: Facebook Ads Cloud Source
   - path: /connections/sources/catalog/cloud-apps/facebook-lead-ads

src/_includes/content/facebook-ldu-intro.md

@@ -0,0 +1,9 @@
+In July 2020, Facebook released [Limited Data Use feature](https://developers.facebook.com/docs/marketing-apis/data-processing-options) to help businesses comply with the California Consumer Privacy Act (CCPA). This feature limits the way user data is stored and processed for all California residents who opt out of the sale of their data. You can send Limited Data Use data processing parameters to Facebook on each event so that Facebook can appropriately apply the user’s data choice. Segment recommends that you first familiarize yourself on this feature and the [Data Processing Options Facebook accepts](https://developers.facebook.com/docs/marketing-apis/data-processing-options).
+
+This destination supports the following parameters:
+
+* **Data Processing Options**
+* **Data Processing Options Country**
+* **Data Processing Options State**
+
+You can enable the feature using the **Use Limited Data Use** destination setting and control it using Data Processing Initialization Parameters.

src/_includes/content/facebook-ldu-params.md

@@ -0,0 +1,13 @@
+### Data Processing Destination Setting
+
+You can change the **Use Limited Data Use** destination setting to enable or disable Limited Data Use. This must be enabled (set to “on”) if you want to send data processing parameters as part of the the Limited Data Use feature.
+
+### Data Processing Initialization Parameters
+
+The Data Processing parameters you set are the Data Processing Options Segment uses when sending data to Facebook. By default, Segment uses the following Data Processing Parameters:
+
+| **Data Processing Parameter**       | **Default Value** | **What it means**                               |
+| ----------------------------------- | ----------------- | ----------------------------------------------- |
+| **Data Processing Options**         | `["LDU"]`         | Use Facebook’s Limited Data Use processing      |
+| **Data Processing Options Country** | `0`               | Use Facebook’s geolocation to determine country |
+| **Data Processing Options State**   | `0`               | Use Facebook’s geolocation to determine state   |

src/connections/destinations/catalog/facebook-app-events/index.md

@@ -155,6 +155,67 @@ The most important events that can help advertisers improve campaign ROI are the
 
 In addition, there are special requirements for dynamic ads. These events are marked with "m" for dynamic ads for mobile, and "t" for dynamic ads for travel within Segment's Facebook App Events settings page.
 
+## Limited Data Use
+
+{% include content/facebook-ldu-intro.md %}
+
+> info ""
+> The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations.
+
+{% include content/facebook-ldu-params.md %}
+
+Facebook uses the `context.ip` to determine the geolocation of the event.
+
+You can manually change the Data Processing parameters by adding settings to the `integrations` object.
+
+#### Server-side library
+
+The example below shows how you might set custom Data Processing parameters for a Segment server library.
+
+```javascript
+// node library example
+
+analytics.track({
+  event: 'Membership Upgraded',
+  userId: '97234974',
+  integrations: {
+    "Facebook App Events": {
+      "dataProcessingOptions": [[], 1,1000]
+    }
+  }
+})
+```
+
+#### iOS Device Mode
+
+When you use Segment’s mobile libraries, you must set the Data Processing Options when you declare the destination in your app delegate’s instance. The example below shows how you might set custom Data Processing parameters in an iOS project.
+
+```objc
+// Add the bundle FB integration SDK
+// Set data processing values.
+SEGFacebookAppEventsIntegrationFactory *fb = [SEGFacebookAppEventsIntegrationFactory instance];
+[fb setDataProcessingOptions:@[ @"LDU" ] forCountry:1 forState: 1000];
+[config use:fb];
+```
+
+#### Android and iOS Cloud Mode
+
+To send the Data Processing Parameters in cloud mode on iOS or Android, you can set them in the integrations object. The example below shows how you might set custom Data Processing parameters in Android.
+
+```java
+Object[] dataProcessingOptions = new Object[3]
+dataProcessingOptions[0] = {'LDU'} // options
+dataProcessOptions[1] = 1 // country
+dataProcessingOptions[2] = 1000 // state
+
+Analytics.with(context).track(
+  "Purchased Item",
+  new Properties(),
+  new Options().setIntegrationOptions(
+    "Facebook App Events", new ImmutableMap.Builder<String, Object>().put("dateProcessingOptions", dataProcessingOptions).build());
+)
+```
+
 ## Other Features
 
 ### Facebook Login and Facebook Dialogs

src/connections/destinations/catalog/facebook-offline-conversions/index.md

@@ -1,6 +1,7 @@
 ---
 title: Facebook Offline Conversions Destination
 rewrite: true
+strat: facebook
 ---
 
 [Facebook Offline Conversions](https://www.facebook.com/business/help/1782327938668950?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) enables offline event tracking, so marketers can run campaigns, upload transaction data, and compare in-store transactions.
@@ -277,3 +278,39 @@ analytics.track({
 We will use SHA256 to hash all `match_keys` that include personally identifiable data in compliance with Facebook's privacy requirements.
 
 Keep in mind that Facebook's furthest possible attribution window is 28 days. It is recommended that you send your server side `track` conversions within 62 days of the offline conversion occuring.
+
+## Limited Data Use
+
+{% include content/facebook-ldu-intro.md %}
+
+> info ""
+> The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations.
+
+### Data Processing Destination Setting
+
+You can change the **Use Limited Data Use** destination setting to enable or disable Limited Data Use. This must be enabled (set to “on”) if you want to send data processing parameters as part of the the Limited Data Use feature.
+
+### Data Processing Initialization Parameters
+
+The Data Processing parameters you set are the Data Processing Options Segment uses when sending data to Facebook.
+
+The Facebook API does not accept an IP address field to determine the geolocation of a user. Instead, you would need to set the specific user geography options (**Data Processing Options Country** and **Data Processing Options State**) in the `integrations` object.
+
+> warning ""
+> If the **Use Limited Data Use** destination setting is enabled, but you do *not* pass the Data Processing parameters in the `integrations` object, Segment sends an empty data processing object which disables LDU for this event.
+
+The example below shows how you might set custom Data Processing parameters for a Segment server library.
+
+```javascript
+// node.js library example
+
+analytics.track({
+  event: 'Membership Upgraded',
+  userId: '97234974',
+  integrations: {
+    "Facebook Offline Conversions": {
+      "dataProcessingOptions": [[], 1,1000]
+    }
+  }
+})
+```

src/connections/destinations/catalog/facebook-pixel-server-side/index.md

@@ -3,6 +3,7 @@ title: Facebook Pixel Server-Side Destination
 rewrite: true
 hidden: true
 beta: true
+strat: facebook
 ---
 
 [Facebook Pixel Server-Side API](https://developers.facebook.com/docs/marketing-api/server-side-api) allows advertisers to send events from their servers directly to Facebook. Server-Side events are linked to a pixel and are processed like browser pixel events. This means that Server-Side events are used in measurement, reporting, and optimization in the same way as browser pixel events.
@@ -145,6 +146,33 @@ uses the value of the "Value Field Identifier" setting to determine which
 property to use for the "value" field. This field defaults to
 `price`.
 
+## Limited Data Use
+
+{% include content/facebook-ldu-intro.md %}
+
+> info ""
+> The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations.
+
+{% include content/facebook-ldu-params.md %}
+
+Facebook uses the `context.ip` to determine the geolocation if it exists on the event.
+
+You can manually change the Data Processing parameters by adding settings to the `integrations` object. The example below shows how you might set custom Data Processing parameters in Node.
+
+```javascript
+// node.js library example
+
+    analytics.track({
+      event: 'Membership Upgraded',
+      userId: '97234974',
+      integrations: {
+        "Facebook Pixel Server-Side": {
+          "dataProcessingOptions": [[], 1,1000]
+        }
+      }
+    })
+```
+
 ## Verify Events in Facebook
 
 After you start sending events, you should start seeing them in twenty

src/connections/destinations/catalog/facebook-pixel/index.md

@@ -56,7 +56,7 @@ analytics.identify('ze8rt1u89', {
   name: 'Zaphod Kim',
   gender: 'Male',
   email: '[email protected]',
-  phone: '1-401-826-4421',
+  phone: '1-401-555-4421',
   address: {
     city: 'San Francisco',
     state: 'Ca',
@@ -163,6 +163,29 @@ If you follow Segment's [spec](/docs/connections/spec/identify/#traits), these w
 
 Facebook also accepts an External ID. This can be any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs. In order to send an `external_id` to Facebook you can indicate which user trait you would like Segment to map to `external_id` using the **Client-Side Only: Advanced Match Trait Key for External ID** setting.
 
+## Limited Data Use
+
+{% include content/facebook-ldu-intro.md %}
+
+> info ""
+> The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations.
+
+{% include content/facebook-ldu-params.md %}
+
+Facebook uses the `context.ip` to determine the geolocation of the event.
+
+You can manually change the Data Processing parameters by adding settings to the `integrations` object. For Facebook Pixel, you must store these settings in the [Load object](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/#load-options) so that Segment can set them *before* it calls `init`. The example below shows how you might set custom Data Processing parameters in Analytics.js.
+
+```javascript
+analytics.load("replace_with_your_write_key", {
+  integrations: {
+    'Facebook Pixel': {
+      dataProcessingOptions: [['LDU'], 1, 1000]
+    }
+  }
+});
+```
+
 ## Settings
 
 ### Map Categories to FB Content Types