Merge pull request #3678 from segmentio/revert-3674-revert-3598-DOC-589

Mobile Device Mode Destination Filters Beta (Swift, Kotlin, React Native 2.0) [DOC-589]

Author: stayseesong

src/connections/destinations/destination-filters.md

@@ -3,32 +3,38 @@ title: Destination Filters
 rewrite: true
 ---
 
-Use Destination Filters to prevent certain data from flowing into a destination. With Destination Filters, you can conditionally filter out event properties, traits, and fields, or even filter out the event itself.
+> info ""
+> Destination filters are only available to Business Tier customers.
+>
+> Destination filters for mobile device-mode destinations are in beta and only supports [Swift](/docs/connections/sources/catalog/libraries/mobile/swift-ios#destination-filters), [Kotlin](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/#destination-filters) and [React Native 2.0](/docs/connections/sources/catalog/libraries/mobile/react-native/#destination-filters) libraries.
+
+Use destination filters to prevent certain data from flowing into a destination. You can conditionally filter out event properties, traits, and fields, or even filter out the event itself.
+
+You can configure destination filters on cloud-mode, mobile, and web device-mode and actions-based destinations.  With device-mode destinations, you can use the same user interface or API mechanism that you use for your cloud-mode destinations, and have those filters acted upon for device-mode destinations on web and mobile.
 
-Common use cases for Destination Filters include:
+Common use cases for destination filters include:
 - Managing PII (personally identifiable information) by blocking fields from reaching certain destinations
 - Controlling event volume by sampling or dropping unnecessary events for specific destinations
 - Increasing data relevance in your destinations by removing unused or unwanted data
 - Preventing test or internally-generated events from reaching your production tools
 
-> info ""
-> Destination Filters are only available to Business Tier customers.
-
 ### Limitations
 
-Keep the following limitations in mind when you use Destination Filters:
+Keep the following limitations in mind when you use destination filters:
 
-- Segment applies Destination Filters one at a time in the order that they appear in your workspace.
-- Destination Filters can only be applied to cloud-mode (server-side) streaming destinations.
-- Device-mode destinations aren't supported.
-- You can't apply Destination Filters to Warehouses or S3 destinations.
+- Segment applies destination filters one at a time in the order that they appear in your workspace.
+- You can't apply destination filters to Warehouses or S3 destinations.
 - Each filter can only apply to one source-destination pair.
+- *(For device-mode)* Destination filters don't apply to items that are added to the payload server-side such as IP addresses.
+- *(For device-mode)* Destination filters don't filter on native events that the destination SDK collects. Instead, you can use the load option to conditionally load relevant bundled JavaScript on the page. See the docs for [load options](/docs/connections/sources/catalog/libraries/website/javascript/#load-options).
+- *(For device-mode)* Destination filters don't filter some fields that are collected by the destination SDK outside of Segment such as `page.url` and `page.referrer`.
+- *(For web device-mode)* Destination filters for web device-mode only supports the Analytics.js 2.0 source. You need to enable device mode destination filters for your Analytics.js source. To do this, go to your Javascript source and navigate to **Settings > Analytics.js** and turn the toggle on for **Destination Filters**.
 
 [Contact Segment](https://segment.com/help/contact/){:target="_blank"} if these limitations impact your use case.
 
-## Create a Destination Filter
+## Create a destination filter
 
-To create a Destination Filter:
+To create a destination filter:
 1. Go to **Connections > Destinations** and select your destination.
 2. Click on the **Filters** tab of your destination.
 3. Click **+ New Filter**.
@@ -38,11 +44,11 @@ To create a Destination Filter:
 7. Name your filter and click the toggle to enable it.
 8. Click **Save**.
 
-## Destination Filters API
+## Destination filters API
 
-The Destination Filters API provides more power than Segment's dashboard Destination Filters settings. With the API, you can create complex filters that are conditionally applied using Segment's [Filter Query Language (FQL)](/docs/api/config-api/fql/).
+The destination filters API provides more power than Segment's dashboard destination filters settings. With the API, you can create complex filters that are conditionally applied using Segment's [Filter Query Language (FQL)](/docs/api/config-api/fql/).
 
-The Destination Filters API offers four different filter types:
+The destination filters API offers four different filter types:
 
 | Filter             | Details                                                      |
 | ------------------ | ------------------------------------------------------------ |
@@ -55,7 +61,7 @@ To learn more, read Segment's [Destination Filters API docs](https://docs.segmen
 
 ## Examples
 
-The following examples illustrate common Destinations Filters use cases:
+The following examples illustrate common destinations filters use cases:
 * [PII management](#pii-management)
 * [Control event volume](#control-event-volume)
 * [Cleaner data](#cleaner-data)
@@ -67,7 +73,7 @@ The following examples illustrate common Destinations Filters use cases:
 
 Example: Remove email addresses from `context` and `properties`:
 
-Property-level allowlisting is available with Segment's API. Using Destination Filters, you can configure a rule that removes email addresses from `context` and `properties`. As a result, Segment only sends traits without PII to the destination.
+Property-level allowlisting is available with Segment's API. Using destination filters, you can configure a rule that removes email addresses from `context` and `properties`. As a result, Segment only sends traits without PII to the destination.
 
 
 ![PII management example](images/destination-filters/pii_example.png)
@@ -96,31 +102,31 @@ In the example below, the rule prevents an event from sending if `Order Complete
 
 ### Sample a percentage of events
 
-Using the [Destination Filters API](https://docs.segmentapis.com/tag/Destination-Filters){:target="_blank"}, you can create a rule to randomly sample video heartbeat events.
+Using the [destination filters API](https://docs.segmentapis.com/tag/Destination-Filters){:target="_blank"}, you can create a rule to randomly sample video heartbeat events.
 
 ### Drop events
 
-[Watch this Destination Filters walkthrough](https://www.youtube.com/watch?v=47dhAF1Hoco){:target="_blank"} to learn how to use event names to filter events sent to destinations.
+[Watch this destination filters walkthrough](https://www.youtube.com/watch?v=47dhAF1Hoco){:target="_blank"} to learn how to use event names to filter events sent to destinations.
 
 ## Important notes
 
 #### Conflicting settings
 
-Some destinations offer settings that also allow you to filter data. For example, the Facebook App Events destination allows you to map `Screen` events to `Track` events. Because Destination Filters are evaluated and applied _before_ the Destination settings are applied, they can conflict with your settings.
+Some destinations offer settings that also allow you to filter data. For example, the Facebook App Events destination allows you to map `Screen` events to `Track` events. Because destination filters are evaluated and applied _before_ the destination settings are applied, they can conflict with your settings.
 
-For example, if you have a Destination Filter that filters Track events _and_ you have the **Use Screen Events as Track Events** setting enabled, `Track` events drop, but `Screen` events still process. The destination settings transform it into a `Track` event - *after* the filters.
+For example, if you have a destination filter that filters Track events _and_ you have the **Use Screen Events as Track Events** setting enabled, `Track` events drop, but `Screen` events still process. The destination settings transform it into a `Track` event - *after* the filters.
 
 #### Error handling
 
-Segment makes effort to ensure that Destination Filters can handle unexpected situations. For example, if you use the `contains()` FQL function on the `null` field, Segment returns `false` instead of returning an error. If Segment can't infer your intent, Segment logs an internal error and drops the event. Segment defaults to this behavior to prevent sensitive information, like a PII filter, from getting through.
+Segment makes effort to ensure that destination filters can handle unexpected situations. For example, if you use the `contains()` FQL function on the `null` field, Segment returns `false` instead of returning an error. If Segment can't infer your intent, Segment logs an internal error and drops the event. Segment defaults to this behavior to prevent sensitive information, like a PII filter, from getting through.
 
 Errors aren't exposed in your Destination's Event Deliverability tab. For help diagnosing missing destination filter events, [contact Segment](https://segment.com/help/contact/){:target="_blank"}.
 
 ## FAQs
 
-#### How do Destination Filters work with array properties?
+#### How do destination filters work with array properties?
 
-Destination Filters can filter properties out of objects nested in an array. For example, you can filter out the `price` property of every object in an array at `properties.products`. You can also filter out an entire array from the payload. However, you can't drop nested objects in an array or filter properties out of a single object in an array.
+Destination filters can filter properties out of objects nested in an array. For example, you can filter out the `price` property of every object in an array at `properties.products`. You can also filter out an entire array from the payload. However, you can't drop nested objects in an array or filter properties out of a single object in an array.
 
 To block a specific property from all of the objects within a properties array, set the filter using the following the format: `<propertyType>.<arrayName>.<arrayElementLabel>​`.
 
@@ -136,7 +142,7 @@ Segment supports 10 filters per destination. If you need help consolidating filt
 
 #### Can I set multiple `Only Send` destination filters?
 
-Segment evaluates multiple `Only Send` filters against each other and resolves Destination Filters in order. If multiple `Only Send` filters conflict with each other, Segment won't send information downstream.
+Segment evaluates multiple `Only Send` filters against each other and resolves destination filters in order. If multiple `Only Send` filters conflict with each other, Segment won't send information downstream.
 
 #### How many properties can I view in the filter dropdown?
 
@@ -150,14 +156,14 @@ To filter out events from warehouses, use Selective Sync.
 
 Generally, only Track calls have *name* properties, which correspond to the *event* field in an event.
 
-#### How can I find out when new Destination Filters have been added or removed?
+#### How can I find out when new destination filters have been added or removed?
 
-The Activity Feed shows the action, date, and user who performed the action when a Destination Filter is created, modified, enabled, disabled, or deleted. You can also subscribe to notifications for any of these changes in the **Activity Feed** settings page.
+The Activity Feed shows the action, date, and user who performed the action when a destination filter is created, modified, enabled, disabled, or deleted. You can also subscribe to notifications for any of these changes in the **Activity Feed** settings page.
 
 #### Why am I getting a permissions denied error when I try to save a filter?
 
 You must have write access to save and edit filters. Read permission access only allows viewing and testing access.
 
 #### How can I test my filter?
 
-Use the Destination Filter tester during setup to verify that you're filtering out the right events. Filtered events show up on the schema page but aren't counted in event deliverability graphs.
+Use the destination filter tester during setup to verify that you're filtering out the right events. Filtered events show up on the schema page but aren't counted in event deliverability graphs.

src/connections/sources/catalog/libraries/mobile/kotlin-android/index.md

@@ -340,8 +340,8 @@ analytics.add(yourPlugin)
 ```
 
 ### Example projects using Analytics-Kotlin
-See how different platforms and languages use Analytics-Kotlin in different [example projects](https://github.com/segmentio/analytics-kotlin/tree/main/samples).
-The example projects contain sample [plugins](https://github.com/segmentio/analytics-kotlin/tree/main/samples/kotlin-android-app/src/main/java/com/segment/analytics/next/plugins) and [destination plugins](https://github.com/segmentio/analytics-kotlin/tree/main/samples/kotlin-android-app-destinations/src/main/java/com/segment/analytics/destinations/plugins) you can utilize.
+See how different platforms and languages use Analytics-Kotlin in different [example projects](https://github.com/segmentio/analytics-kotlin/tree/main/samples){:target="_blank"}.
+The example projects contain sample [plugins](https://github.com/segmentio/analytics-kotlin/tree/main/samples/kotlin-android-app/src/main/java/com/segment/analytics/next/plugins){:target="_blank"} and [destination plugins](https://github.com/segmentio/analytics-kotlin/tree/main/samples/kotlin-android-app-destinations/src/main/java/com/segment/analytics/destinations/plugins){:target="_blank"} you can use.
 
 ## Utility methods
 The Analytics-Kotlin utility methods help you work with plugins from the analytics timeline. They include:
@@ -442,6 +442,30 @@ analytics.reset()
 {% endcodeexampletab %}
 {% endcodeexample %}
 
+## Destination filters
+> info ""
+> Destination filters are only available to Business Tier customers.
+>
+> Destination filters on mobile device-mode destinations are in beta and only supports Analytics-Kotlin, [Analytics-Swift](/docs/connections/sources/catalog/libraries/mobile/swift-ios/), and [Analytics-React-Native 2.0](/docs/connections/sources/catalog/libraries/mobile/react-native/).
+
+Use Analytics-Kotlin (Android) to configure [destination filters](docs/connections/destinations/destination-filters/) on your mobile device-mode destinations.
+
+> warning ""
+> Keep [these limitations](/docs/connections/destinations/destination-filters/#limitations) in mind when using destination filters.
+
+
+To get started with destination filters on mobile device-mode destinations using Kotlin:
+
+1. Download and install the dependency.
+  ```java
+    implementation 'com.segment.analytics.kotlin:destination-filters-kotlin:0.1.0'
+  ```
+
+2. Add the plugin.
+  ```java
+    analytics.add(DestinationFilters())
+  ```
+
 ## Build Your own destination
 
 If Segment doesn't support your Kotlin destination, you can build your own with the template Segment provides.

src/connections/sources/catalog/libraries/mobile/react-native/index.md

@@ -491,6 +491,45 @@ These are the example plugins you can use and alter to meet your tracking needs:
 | Firebase            | `@segment/analytics-react-native-plugin-consent-firebase`    |
 | IDFA                | `@segment/analytics-react-native-plugin-idfa`                |
 
+## Destination Filters
+> info ""
+> Destination filters are only available to Business Tier customers.
+>
+> Destination filters on mobile device-mode destinations are in beta and only supports Analytics-React-Native 2.0, [Analytics-Swift](/docs/connections/sources/catalog/libraries/mobile/swift-ios/) and [Analytics-Kotlin](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/).
+
+Use Analytics-React-Native 2.0 to set up [destination filters](docs/connections/destinations/destination-filters/) on your mobile device-mode destinations.
+
+> warning ""
+> You must use Analytics-React-Native version 2.9 or higher to implement destination filters.
+>
+> Keep [these limitations](/docs/connections/destinations/destination-filters/#limitations) in mind when using destination filters.
+
+To get started with destination filters on mobile device-mode destinations using Analytics-React-Native 2.0:
+1. Download and install the `@segment/analytics-react-native-plugin-destination-filters` package as a dependency in your project.
+    * Using NPM:
+      ```npm
+      npm install --save @segment/analytics-react-native-plugin-destination-filters
+      ```
+    * Using Yarn:
+      ```yarn
+      yarn add @segment/analytics-react-native-plugin-destination-filters
+      ```
+2. Follow the instructions for [adding plugins](/docs/connections/sources/catalog/libraries/mobile/react-native/#adding-plugins) on the main Analytics client.
+3. Add `DestinationFiltersPlugin` after you create your Segment client.
+
+    ```kotlin
+    import { createClient } from '@segment/analytics-react-native';
+
+    import { DestinationFiltersPlugin } from '@segment/analytics-react-native-plugin-destination-filters';
+
+    const segmentClient = createClient({
+      writeKey: 'SEGMENT_KEY'
+    });
+
+    segmentClient.add({ plugin: new DestinationFiltersPlugin() });
+    segment.add({ plugin: new FirebasePlugin() })
+    ```
+
 ## Supported Destinations
 Segment supports a large number of [Cloud-mode](/docs/connections/destinations/#connection-modes) destinations. Segment also supports the below destinations for Analytics React Native 2.0 in device-mode, with more to follow:
 - [Adjust](https://www.npmjs.com/package/@segment/analytics-react-native-plugin-adjust){:target="_blank"}