Merge pull request #3598 from segmentio/DOC-589

stayseesong · web-flow · commit 125a2f18bb07 · 2022-10-17T15:58:05.000-07:00
Mobile Device Mode Destination Filters Beta (Swift, Kotlin, React Native 2.0) [DOC-589]
diff --git a/src/connections/destinations/destination-filters.md b/src/connections/destinations/destination-filters.md
@@ -3,30 +3,35 @@ 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:
 
 - 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.
 - 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 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:
 1. Go to **Connections > Destinations** and select your destination.
@@ -38,7 +43,7 @@ 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/).
 
diff --git a/src/connections/sources/catalog/libraries/mobile/kotlin-android/index.md b/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.
diff --git a/src/connections/sources/catalog/libraries/mobile/react-native/index.md b/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"}
diff --git a/src/connections/sources/catalog/libraries/mobile/swift-ios/index.md b/src/connections/sources/catalog/libraries/mobile/swift-ios/index.md
@@ -13,7 +13,7 @@ If you're migrating to Analytics-Swift from a different mobile library, you can
 > Analytics-Swift currently supports [these destinations](#supported-destinations) in device-mode, with more to follow. Cloud-mode destinations are also supported.
 
 
-## Getting Started
+## Getting started
 To get started with the Analytics-Swift mobile library:
 
 1. Create a Source in Segment.
@@ -59,6 +59,10 @@ To get started with the Analytics-Swift mobile library:
     `trackApplicationLifecycleEvents`| The default is set to `true`. <br> This automatically tracks lifecycle events. Set to `false` to stop tracking lifecycle events.
     `trackDeepLinks` | The default is set to `true`. <br> This automatically track deep links. Set to `false` to stop tracking Deep Links.
 
+
+    > info ""
+    > Configuration options such as IDFA collection and automatic screen tracking are found in Segment's [Plugin Examples repo](https://github.com/segmentio/analytics-example-plugins/tree/main/plugins/swift){:target="_blank"}.
+
 ## Tracking Methods
 Once you've installed the Analytics-Swift library, you can start collecting data through Segment's tracking methods:
 - [Identify](#identify)
@@ -201,7 +205,7 @@ analytics.alias(newId: "user-123")
 {% endcodeexampletab %}
 {% endcodeexample %}
 
-## Plugin Architecture
+## Plugin architecture
 Segment's plugin architecture enables you to modify and augment how the analytics client works. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done.
 
 Plugins are run through a timeline, which executes in order of insertion based on their entry types. Segment has these 5 entry types:
@@ -330,7 +334,7 @@ analytics.add(plugin: yourIntegration)
 
 Though you can add plugins anywhere in your code, it's best to implement your plugin when you configure the client.
 
-## Utility Methods
+## Utility methods
 The Analytics Swift utility methods help you work with [plugins](#plugin-architecture) from the analytics timeline. They include:
 - [Add](#add)
 - [Find](#find)
@@ -406,6 +410,30 @@ analytics.flush()
 {% 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-Swift, [Analytics-Kotlin](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/), and [Analytics-React-Native 2.0](/docs/connections/sources/catalog/libraries/mobile/react-native/).
+
+Use Analytics-Swift to set up [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 using Swift:
+1. Add the Swift package `git@github.com:segmentio/DestinationFilters-Swift.git` as a dependency through either of these 2 options:
+    1. Your package.swift file
+    2. Xcode
+        1. Xcode 12: **File > Swift Packages > Add Package Dependency**
+        2. Xcode 13: **File > Add Packages...**
+
+    After you install the package, import the package with `import DestinationFilters_Swift` to reference the Destination Filters plugin.
+2. Add the plugin.
+```swift
+analytics.add(DestinationFilters())
+```
+
 ## Ad Tracking and IDFA
 [Segment no longer automatically collects IDFA](/docs/connections/sources/catalog/libraries/mobile/ios/ios14-guide/#segment-no-longer-automatically-collects-idfa). If you need to collect the user's IDFA to pass it to specific destinations, or for other uses, [you can manually pass the IDFA to the Segment SDK](/docs/connections/sources/catalog/libraries/mobile/ios/ios14-guide/#you-can-manually-pass-the-idfa-to-the-segment-sdk).
 
@@ -416,13 +444,13 @@ let idfaPlugin = IDFACollection()
 analytics.add(plugin: idfaPlugin)
 ```
 
-## Supported Destinations
+## Supported destinations
 Segment supports these destinations for Analytics Swift, with more to come:
-* [Amplitude](https://github.com/segment-integrations/analytics-swift-amplitude)
-* [Appsflyer](https://github.com/segment-integrations/analytics-swift-appsflyer)
-* [Facebook App Events](https://github.com/segment-integrations/analytics-swift-facebook-app-events)
-* [Firebase](https://github.com/segment-integrations/analytics-swift-firebase)
-* [Mixpanel](https://github.com/segment-integrations/analytics-swift-mixpanel)
+* [Amplitude](https://github.com/segment-integrations/analytics-swift-amplitude){:target="_blank"}
+* [Appsflyer](https://github.com/segment-integrations/analytics-swift-appsflyer){:target="_blank"}
+* [Facebook App Events](https://github.com/segment-integrations/analytics-swift-facebook-app-events){:target="_blank"}
+* [Firebase](https://github.com/segment-integrations/analytics-swift-firebase){:target="_blank"}
+* [Mixpanel](https://github.com/segment-integrations/analytics-swift-mixpanel){:target="_blank"}
 
 ## FAQs
 ### Can I use the catalog of device-mode destinations from Analytics-iOS?
@@ -431,4 +459,4 @@ No, only the plugins listed above are supported in device-mode for Analytics-Swi
 When you successfully package a plugin in device-mode, you will no longer see the integration listed as `false` in the integrations object for a Segment event. This logic is now packaged in the event metadata, and is not surfaced in the Segment debugger.
 
 ## Changelog
-[View the Analytics-Swift changelog on GitHub](https://github.com/segmentio/analytics-swift/releases).  
+[View the Analytics-Swift changelog on GitHub](https://github.com/segmentio/analytics-swift/releases){:target="_blank"}.  
diff --git a/src/guides/filtering-data.md b/src/guides/filtering-data.md
@@ -43,20 +43,30 @@ Note that destination flags are **case sensitive** and match the destination's n
 
 Your data is sent to your warehouse (if you have one) and into the Segment backend systems regardless of what is in the integrations object.
 
-## Destination Filters
+## Destination filters
 
-[Destination Filters](https://segment.com/docs/connections/destinations/destination-filters/) allow you to control the data flowing into each specific destination, by examining event payloads, and conditionally preventing data from being sent to destinations. You can filter out entire events, or just specific fields in the properties, in the traits, or in the context of your events. Destination filters are not available for, and do not prevent data from reaching your warehouse(s) or S3 destinations.
+[Destination filters](https://segment.com/docs/connections/destinations/destination-filters/) allow you to control the data flowing into each specific destination, by examining event payloads, and conditionally preventing data from being sent to destinations. You can filter out entire events, or just specific fields in the properties, in the traits, or in the context of your events. Destination filters support cloud-based (server-side), actions-based, and mobile and web device-mode destinations.  Destination filters aren't available for, and don't prevent data from reaching your warehouse(s) or S3 destinations.
 
-> note ""
-> **Note**: Destination Filters are available in workspaces that are on a Business Tier plan only. Destination Filters can only be applied to Cloud-mode ("server-side") streaming destinations. Device-mode destinations are not supported.
+> info ""
+> Destination filters are only available in workspaces that are on a Business Tier plan.
+>
+> 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 (Android)](/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.
+
+> warning ""
+> Keep [these limitations](/docs/connections/destinations/destination-filters/#limitations) in mind when using destination filters.
 
 ![](images/destination-filter-create.png)
 
-You can set up Destination Filters from the Segment web app by navigating to the destination from which you want to exclude the data, and clicking the **Destination Filters** tab. From there you can create new filter rules, and edit, enable, and disable existing filters. See the [Destination Filters documentation](https://segment.com/docs/connections/destinations/destination-filters/) for more details.
+To set up destination filters from the Segment web app for the destination from which you want to exclude data:
+1. *(For web device-mode destinations only)* 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**.
+    * **NOTE:** Destination filters for web device-mode only supports the Analytics.js 2.0 source. 
+2. Navigate to **Connections > Destinations** and select the destination you want to set up filters for.
+3. Go to the **Filters** tab and click **+ New Filter** to create a destination filter.
+See the [Destination Filters documentation](/docs/connections/destinations/destination-filters/) for more details.
 
-You can set up Destination filters using the options presented in the Segment web app, or using Segment's Filter Query Logic (FQL). If you use FQL, your query syntax is limited to 5kb per query.
+You can set up destination filters using the options presented in the Segment web app, or using Segment's Filter Query Logic (FQL). If you use FQL, your query syntax is limited to 5kb per query.
 
-## Per-Source Schema Integrations Filters
+## Per-Source schema integrations filters
 
 Integration filters allow you to quickly change which destinations receive specific Track, Identify, or Group events. Access this tool in any Source that is receiving data by navigating to the Schema tab. Schema integration filters are available to workspaces that are on a Business Tier plan only.
 
@@ -68,7 +78,7 @@ The events filtered out of individual destinations using this method still arriv
 
 **Integration filters are all-or-nothing for each event.** If you require more detailed control over which events are sent to specific destinations, you can use Destination Filters to inspect the event payload, and conditionally drop the data or forward it to the destination.
 
-## Schema Event Filters
+## Schema event filters
 
 You can use Schema Event Filters to discard and permanently remove Page, Screen and Track events from event-based sources, preventing them from reaching any destinations or warehouses. Use this if you know that you'll never want to access this data again. This functionality is similar to filtering with the Integrations object, however it can be changed from within the Segment app without touching any code.
 
