generated from segment-integrations/analytics-swift-destination-template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
79 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,25 +1,85 @@ | ||
# Swift Destination Plugin Template | ||
This template is resolved around `ExampleDestination` (to be replaced by you). | ||
# Segment Consent Management - OneTrust Integration | ||
|
||
## What does the template provide | ||
### Data class for holding settings | ||
To standardize fetching and using settings in your destination, we recommend using a Coable class to store your destination settings. If marked `Codable`, it will enable you to retrieve your destination settings in a strongly typed construct. | ||
Add Segment + OneTrust driven consent management support for your application via this plugin for [Analytics-Swift](https://github.com/segmentio/analytics-swift) | ||
|
||
### Settings-related functions | ||
We provide APIs to update your destination settings in `update(settings:type:)`. | ||
`UpdateType.initial` lets you know if this is the intial or subsequent fetch. | ||
This plugin provides the framework to integration Consent Management Platform (CMP) SDKs like OneTrust to supply consent status and potential block events going to device mode destinations. | ||
|
||
`Settings.isDestinationEnabled(key: String)` | ||
- check if your destination is enabled | ||
Read more about Segment's Consent Management solutions [here](https://segment.com/docs/privacy/configure-consent-management/), as well as enabling it for your workspace. | ||
|
||
`Settings.integrationSettings(forKey: String)` | ||
- retrieve a typed destination object | ||
## Getting Started | ||
|
||
### Sample implementation for common destination functions | ||
We have templated common destinations functions like `track`, `identify`, `screen`, `group`, `alias` that you should modify to fit your vendor SDK implementation. Although these functions do not need to return the ending payload, its good practice to do so (for unit testing purposes). | ||
### via Xcode | ||
In the Xcode `File` menu, click `Add Packages`. You'll see a dialog where you can search for Swift packages. In the search field, enter the URL to these repos. | ||
|
||
### Transforming events | ||
Often times, destinations need to transform events (eg: change names, modify properties/traits etc.). We have templated an example of transformation in the `track(event:)` example. we recommend you use this approach to perform any such transformations. This will make your code more legible plus improve code quality. | ||
https://github.com/segment-integrations/analytics-swift-consent | ||
https://github.com/segment-integrations/analytics-swift-consent-onetrust | ||
|
||
### Testing functions for primary functions (to be expanded) | ||
We have provided a very bare minimum template for testing the primary destination APIs. We recommend to use this as a starter and build upon it to get test coverage of most scenarios. | ||
You'll then have the option to pin to a version, or specific branch, as well as which project in your workspace to add it to. Once you've made your selections, click the `Add Package` button. | ||
|
||
### via Package.swift | ||
|
||
Open your Package.swift file and add the following to your `dependencies` section: | ||
|
||
``` | ||
.package( | ||
name: "SegmentConsent", | ||
url: "https://github.com/segment-integrations/analytics-swift-consent.git", | ||
from: "1.0.0" | ||
), | ||
.package( | ||
name: "SegmentConsentOneTrust", | ||
url: "https://github.com/segment-integrations/analytics-swift-consent-onetrust.git", | ||
from: "1.0.0" | ||
), | ||
``` | ||
|
||
Next you'll need to write some setup/init code where you have your | ||
Analytics setup: | ||
|
||
```swift | ||
import Segment | ||
import SegmentConsent | ||
import SegmentConsentOneTrust | ||
|
||
... | ||
|
||
let analytics = Analytics(configuration: Configuration(writeKey: "<your write key>") | ||
.flushAt(1) | ||
.trackApplicationLifecycleEvents(true)) | ||
|
||
// Add the Segment Consent Manager plugin. | ||
// We'll need the value of this so we can call | ||
// start(), to once OneTrust is configured. | ||
let consentManager = ConsentManager(provider: OneTrustProvider()) { | ||
// we were notified (optionally) that consent changed. | ||
print("Consent Changed") | ||
} | ||
|
||
// Optionally add the IDFAConsent plugin if ATT is to be used. | ||
// It will capture ATT changes and notify the consent manager. | ||
// You'll need to copy this code into YOUR codebase and modify it | ||
// to suit your needs. | ||
// NOTE: The code for this plugin can be found in the example app. | ||
analytics.add(plugin: IDFAConsent()) | ||
|
||
// once we do the setup, onetrust triggers the consent UI to pop up on | ||
// it's own. you can do it manually if you prefer though, but any way | ||
// you slice it, you'll need a uiviewcontroller. | ||
if let mainViewController = UIApplication.shared.mainViewController { | ||
OTPublishersHeadlessSDK.shared.setupUI(mainViewController, UIType: .preferenceCenter) | ||
} | ||
|
||
// Tell OneTrush SDK to start. | ||
OTPublishersHeadlessSDK.shared.startSDK( | ||
storageLocation: "cdn.cookielaw.org", | ||
domainIdentifier: "<your domain identifier>", | ||
languageCode: "en" | ||
) { response in | ||
// Tell the Semgnet consent manager to start. Until this happens, | ||
// all events are queued so they can get the proper stamps and treatment. | ||
consentManager.start() | ||
} | ||
|
||
``` | ||
|
||
The Consent Manager plugin will automatically add a ConsentBlockingPlugin to any device mode destinations, so there's no extra steps for you to do in your code. Blocking for cloud mode destinations will be handled server-side at Segment. |