Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DIA-4246 MIGRATION.md guide added to help in migration from 2.x.x to 3.0.0 #64

Merged
merged 4 commits into from
Jul 11, 2024
Merged

DIA-4246 MIGRATION.md guide added to help in migration from 2.x.x to 3.0.0 #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
04636a7
`MIGRATION.md` guide added to help in migration from 2.x.x to 3.0.0
Nevazhnovu Jul 6, 2024
283d27f
Update `README.md`
Nevazhnovu Jul 8, 2024
29cc409
Update `MIGRATION.md`
Nevazhnovu Jul 9, 2024
a501ec0
Update MIGRATION.md
tom-win87 Jul 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Upgrade from 2.x.x to 3.0.0

## Instantiate consent UI

In version 3.0.0, the namespace of the library was changed to `ConsentManagementProvider`:

```c#
using ConsentManagementProvider;
```

## CMP facade
CMP class was moved from using the static methods to using the static instance (singleton pattern). Replace `CMP` with `CMP.Instance` before usage of each method.

### Initialize
In order to instantiate & trigger `Consent Message Web View`, you must call the `CMP.Instance.Initialize`.

```diff
- CMP.Initialize(spCampaigns: spCampaigns,
+ CMP.Instance.Initialize(spCampaigns: spCampaigns,
accountId: 22,
propertyId: 16893,
propertyName: "mobile.multicampaign.demo",
- gdpr: true,
- ccpa: true,
- usnat: true,
language: MESSAGE_LANGUAGE.ENGLISH,
- gdprPmId: "488393",
- ccpaPmId: "509688",
- usnatPmId: "943886",
campaignsEnvironment: CAMPAIGN_ENV.PUBLIC,
messageTimeoutInSeconds: 30,
- transitionCCPAAuth: false,
- supportLegacyUSPString: false);
```

| Field | **Description** |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gdprPmId` | Used only in `LoadPrivacyManager` |
| `ccpaPmId` | Used only in `LoadPrivacyManager` |
| `usnatPmId` | Used only in `LoadPrivacyManager` |
| `transitionCCPAAuth` | Moved to `SPCampaign` |
| `supportLegacyUSPString` | Moved to `SPCampaign` |

## SPCampaign
`transitionCCPAAuth` and `supportLegacyUSPString` are now part of `SpCampaign`. Parameters work only for the `usnat` campaign.

``` c#
SpCampaign usnat = new SpCampaign(campaignType: CAMPAIGN_TYPE.USNAT, targetingParams: usnatParams, transitionCCPAAuth: true, supportLegacyUSPString: true);
spCampaigns.Add(usnat);
```

### GetSpConsent
This getter is used to retrieve `SpConsents` data. After calling, it checks the platform (Android or iOS) and returns the `SPConsents` object with the following structure:

```diff
SpConsents
|-- gdpr?
| |-- applies: bool
| |-- consents: GdprConsent
+ | |-- applies: bool
| |-- uuid: String?
| |-- tcData: Map<String, Object>
| |-- grants: Map<String, GDPRPurposeGrants>
| |-- euconsent: String
| |-- acceptedCategories: List<String>
| |-- consentStatus: ConsentStatus
| |-- googleConsentMode: SPGCMData?
| |-- adStorage: SPGCMData.Status?
| |-- analyticsStorage: SPGCMData.Status?
| |-- adUserData: SPGCMData.Status?
| |-- adPersonalization: SPGCMData.Status?
|-- ccpa?
| |-- applies: bool
| |-- consents: CcpaConsent
+ | |-- applies: bool
| |-- uuid: String?
| |-- rejectedCategories: List<String>
| |-- rejectedVendors: List<String>
| |-- status: String?
| |-- uspstring: String
| |-- childPmId: String
| |-- signedLspa: bool
| |-- consentStatus: ConsentStatus?
+ | |-- GPPData: Dictionary<string, object>?
|-- usnat?
|-- applies: bool
|-- consents: CcpaConsent
|-- uuid: String?
|-- applies: bool
|-- consentStrings: List<ConsentString>
|-- vendors: List<Consentable> //[{id: String, consented: bool }]
|-- categories: List<Consentable> //[{id: String, consented: bool }]
|-- statuses: StatusesUsnat
|-- rejectedAny: bool?
|-- consentedToAll: bool?
|-- consentedToAny: bool?
|-- hasConsentData: bool?
|-- sellStatus: bool?
|-- shareStatus: bool?
|-- sensitiveDataStatus: bool?
|-- gpcStatus: bool?
+ |-- GPPData: Dictionary<string, object>?
```
57 changes: 33 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Sourcepoint's plug and play Unity SDK can be integrated with both Android and iOS.

> **Note**: If you have updated from version 2.x.x to 3.0.0, please read [`MIGRATION.md`](MIGRATION.md)

> **Note**: The Unity SDK can not be demoed using Unity's Editor since it embeds native SDKs and those only work in their respective platforms.
> <br><br>Additionally, this SDK utilizes [ExternalDependencyManager by Google](https://github.com/googlesamples/unity-jar-resolver) in order to fetch native SDKs and their dependencies. Ensure all the dependencies mentioned in `Assets/ExternalDependencyManager/Editor/SourcepointDependencies.xml` are resolved before building your application.

Expand All @@ -16,7 +18,7 @@ Please also note that in order to build a project:
To start, include the following library namepsace in your script:

```c#
using ConsentManagementProviderLib;
using ConsentManagementProvider;
```

Construct `List<SpCampaign>` which contains `SpCampaign` objects. Each `SpCampaign` object should consist of `CAMPAIGN_TYPE` along with the `TargetingParams` you need.
Expand All @@ -41,24 +43,16 @@ Construct `List<SpCampaign>` which contains `SpCampaign` objects. Each `SpCampai
spCampaigns.Add(usnat);
```

In order to instantiate & trigger `Consent Message Web View`, you must call the `CMP.Initialize` function in `Awake` along with `spCampaigns`, `accountId`, `propertyId`, `propertyName`, `gdpr`, `ccpa`, `usnat`,`gdprPmId`, `ccpaPmId`, `usnatPmId` and `language`.<br/> <br/>Additionally, you can also specify a `messageTimeout` which, by default, is set to **30 seconds**.
In order to instantiate & trigger `Consent Message Web View`, you must call the `CMP.Instance.Initialize` function in `Awake` along with `spCampaigns`, `accountId`, `propertyId`, `propertyName` and `language`.<br/> <br/>Additionally, you can also specify a `messageTimeout` which, by default, is set to **30 seconds**.

```c#
CMP.Initialize(spCampaigns: spCampaigns,
CMP.Instance.Initialize(spCampaigns: spCampaigns,
accountId: 22,
propertyId: 16893,
propertyName: "mobile.multicampaign.demo",
gdpr: true,
ccpa: true,
usnat: true,
language: MESSAGE_LANGUAGE.ENGLISH,
gdprPmId: "488393",
ccpaPmId: "509688",
usnatPmId: "943886",
campaignsEnvironment: CAMPAIGN_ENV.PUBLIC,
messageTimeoutInSeconds: 30,
transitionCCPAAuth: false,
supportLegacyUSPString: false);
messageTimeoutInSeconds: 30);
```

| Field | **Description** |
Expand All @@ -68,11 +62,6 @@ In order to instantiate & trigger `Consent Message Web View`, you must call the
| `propertyId` | ID for property found in the Sourcepoint portal |
| `propertyName` | Name of property found in the Sourcepoint portal |
| `language` | Force a message to be displayed in a certain language. Look `MESSAGE_LANGUAGE` for all available languages |
| `gdprPmId` | Id of the privacy manager for `gdpr` campaign |
| `ccpaPmId` | Id of the privacy manager for `ccpa` campaign |
| `usnatPmId` | Id of the privacy manager for `usnat` campaign |
| `transitionCCPAAuth` | Transfer opt-in/opt out preferences from U.S. Privacy (Legacy) to U.S. Multi-State Privacy [ios](https://github.com/SourcePointUSA/ios-cmp-app?tab=readme-ov-file#transfer-opt-inopt-out-preferences-from-us-privacy-legacy-to-us-multi-state-privacy), [android](https://github.com/SourcePointUSA/android-cmp-app?tab=readme-ov-file#transfer-opt-inopt-out-preferences-from-us-privacy-legacy-to-us-multi-state-privacy) |
| `supportLegacyUSPString` | Support U.S. Privacy (Legacy) with U.S. Multi-State Privacy [ios](https://github.com/SourcePointUSA/ios-cmp-app?tab=readme-ov-file#support-us-privacy-legacy-with-us-multi-state-privacy) |

> **Note**: It may take a frame to initialize the CMP library, so we strongly recommend that you `Initialize` in `Awake` separately from `LoadMessage`. We recommend that you `LoadMessage` in `Start` (see example below).

Expand All @@ -81,7 +70,7 @@ When the SDK receives the `LoadMessage` call, it will instantiate a webview if t
```c#
private void Start()
{
CMP.LoadMessage(authId: null); // or pass it a String if you wish to use authenticated consent
CMP.Instance.LoadMessage(authId: null); // or pass it a String if you wish to use authenticated consent
}
```

Expand All @@ -90,7 +79,7 @@ Utilize the following method if an end-user requests to have their data deleted:
```c#
private void ClearData()
{
CMP.ClearAllData();
CMP.Instance.ClearAllData();
}
```

Expand All @@ -99,7 +88,7 @@ In order to free memory, call `Dispose` as illustrated in the following example
```c#
private void OnDestroy()
{
CMP.Dispose();
CMP.Instance.Dispose();
}
```

Expand Down Expand Up @@ -181,7 +170,7 @@ The solution is ready. Configure it and deploy!
Both calling & handling workflows are implemented in the `ConsentMessageProvider` and `ConsentEventHandler` scripts of our example app accordingly. Feel free to use these components.

```c#
using ConsentManagementProviderLib;
using ConsentManagementProvider;
using System;
using UnityEngine;

Expand Down Expand Up @@ -241,7 +230,7 @@ Once a player has completed the consent flow, you might want to provide a way fo
```c#
public void OnPrivacyManagerButtonClick()
{
CMP.LoadPrivacyManager(campaignType: CAMPAIGN_TYPE.GDPR,
CMP.Instance.LoadPrivacyManager(campaignType: CAMPAIGN_TYPE.GDPR,
pmId: "488393",
tab: PRIVACY_MANAGER_TAB.DEFAULT);
}
Expand All @@ -268,6 +257,7 @@ This getter is used to retrieve `SpConsents` data. After calling, it checks the
|-- gdpr?
| |-- applies: bool
| |-- consents: GdprConsent
| |-- applies: bool
| |-- uuid: String?
| |-- tcData: Map<String, String>
| |-- grants: Map<String, GDPRPurposeGrants>
Expand All @@ -282,6 +272,7 @@ This getter is used to retrieve `SpConsents` data. After calling, it checks the
|-- ccpa?
| |-- applies: bool
| |-- consents: CcpaConsent
| |-- applies: bool
| |-- uuid: String?
| |-- rejectedCategories: List<String>
| |-- rejectedVendors: List<String>
Expand All @@ -290,6 +281,7 @@ This getter is used to retrieve `SpConsents` data. After calling, it checks the
| |-- childPmId: String
| |-- signedLspa: bool
| |-- consentStatus: ConsentStatus?
| |-- GPPData: Dictionary<string, object>?
|-- usnat?
|-- applies: bool
|-- consents: CcpaConsent
Expand All @@ -307,12 +299,13 @@ This getter is used to retrieve `SpConsents` data. After calling, it checks the
|-- shareStatus: bool?
|-- sensitiveDataStatus: bool?
|-- gpcStatus: bool?
|-- GPPData: Dictionary<string, object>?
```

This method may return null. Sample usage:

```c#
CMP.GetSpConsents()
CMP.Instance.GetSpConsents()
```

## Verifying end-user consent for a given vendor
Expand All @@ -324,7 +317,7 @@ If the vendor you're interested in verifying consent for is part of the IAB grou
For vendors that are not part of the IAB, you can verify the user consented to the vendor with the following:

```c#
consents = CMP.GetSpConsents();
consents = CMP.Instance.GetSpConsents();

// for GDPR
bool isMyGDPRVendorConsented = consents.gdpr.consents.grants["a_vendor_id"].vendorGrant;
Expand Down Expand Up @@ -368,6 +361,22 @@ void DeleteCustomConsentGDPR(

It's important to notice, this methods are intended to be used for **custom** vendors and purposes only. For IAB vendors and purposes, it's still required to get consent via the consent message or privacy manager.

## Transfer opt-in/opt out preferences from U.S. Privacy (Legacy) to U.S. Multi-State Privacy
For full information please visit the links: [ios](https://github.com/SourcePointUSA/ios-cmp-app?tab=readme-ov-file#transfer-opt-inopt-out-preferences-from-us-privacy-legacy-to-us-multi-state-privacy), [android](https://github.com/SourcePointUSA/android-cmp-app?tab=readme-ov-file#transfer-opt-inopt-out-preferences-from-us-privacy-legacy-to-us-multi-state-privacy).
Parameters work only for the usnat campaign. Usage:
```c#
SpCampaign usnat = new SpCampaign(campaignType: CAMPAIGN_TYPE.USNAT, targetingParams: usnatParams, transitionCCPAAuth: true);
spCampaigns.Add(usnat);
```

## Support U.S. Privacy (Legacy) with U.S. Multi-State Privacy
For full information please visit the links: [ios](https://github.com/SourcePointUSA/ios-cmp-app?tab=readme-ov-file#support-us-privacy-legacy-with-us-multi-state-privacy), [android](https://github.com/SourcePointUSA/android-cmp-app?tab=readme-ov-file#support-us-privacy-legacy-with-us-multi-state-privacy).
Parameters work only for the usnat campaign. Usage:
```c#
SpCampaign usnat = new SpCampaign(campaignType: CAMPAIGN_TYPE.USNAT, targetingParams: usnatParams, supportLegacyUSPString: true);
spCampaigns.Add(usnat);
```

# Build for iOS

Since Unity Editor exports the pre-built project to Xcode on iOS build, there are several necessary steps to perform so you can compile your solution. They are implemented inside the `CMPPostProcessBuild` [PostProcessBuild] script. Supplement or modify it if it is needed.
Expand Down