@osano/osano-cmp-react-native 0.12.0 → 0.14.0

package/README.dev.md

@@ -26,9 +26,24 @@ From the root folder, run the following:
 corepack yarn install
 corepack yarn prepare
 cd example/ios && pod install && cd ../..
+cd example/ios && echo export NODE_BINARY=$(command -v node) > .xcode.env && cd ../.. # do once
+cp example/.env.example example/.env # do once
 corepack yarn example android # or ios
+
+# alternatively
+cd example && corepack yarn start android # or ios
 ```
 
+### Specifying run destination
+
+**iOS**
+
+`corepack yarn example ios --simulator "iPhone 15 Pro"`
+
+**Android**
+
+`// TODO`
+
 ## Running Tests
 
 Testing should be done through both the example integration and the package itself.
@@ -49,10 +64,222 @@ npm test
 
 ### Testing the examples
 
-_Needs to be written_
+#### Build the test applications from local builds
+
+- iOS
+
+1. Run the iOS application locally via `yarn example ios`
+1. Open the Derived Data in your XCode folder `~/Library/Developer/XCode/DerivedData`
+1. One of the folders in the `DerivedData` folder will contain a `Build` folder
+1. Open `Build/Products/<device-type>`
+1. The .app file will be `OsanoCMPExample` with a file type `Application`
+
+- Android
+
+1. Run the android example application locally via `yarn example android`
+1. In `Android Studio` under `Project` open `app/build/outputs/apk/<release-or-debug>/` to get the apk file
+
+Both files can be sent to coworkers with an ios simulator or android emulator to run for testing
 
 ## Troubleshooting
 
 1.  If the `run` command fails saying there is no development project, make sure to open the relevant simulator/emulator before running.
 1.  If there are significant errors citing duplicates, it is likely you ran `npm i` in the packages folder. These files should be removed via `rm -rf node_modules` in the `packages/osano-cmp-react-native` folder from the command line
 1.  For initial developing and testing make sure you have a relatively recent simulator on iOS and emulator on Android. Old devices running old OS can cause unnecessary issues
+1.  Building the iOS example from Xcode might result in a `Command PhaseScriptExecution failed with a nonzero exit code`. This is caused by a missing `.xcode.env` file that contains an entry for NODE_PATH. Resolve by running `echo export NODE_BINARY=$(command -v node) > .xcode.env` from the `example/ios` directory.
+
+=======
+
+The Osano ConsentSDK for iOS is a native framework that integrates with the Consent Management Platform on the [Osano Website](https://my.osano.com). It is necessary to have an account, and a Cookie Consent configuration created and published in order for this SDK to be able to record end-user consents.
+
+### Installation
+
+---
+
+We use NPM to manage and install the SDK package.
+
+1. At the top level of your project run `npm install @osano/osano-cmp-react-native`
+
+#### Native iOS installation
+
+NPM uses cocoapods to install the native iOS portion of modules[CocoaPods](https://guides.cocoapods.org/)
+
+1. Install Cocoapods using [Cocoapods - Getting Started](https://guides.cocoapods.org/using/getting-started.html).
+1. Run `pod install` from inside the iOS folder in your project
+
+#### Native Android installation
+
+1. Run a gradle sync after `@osano/osano-cmp-react-native` has been added to your package manager
+
+### Integration
+
+## How do I use it?
+
+- [ConsentManager](#consentmanager)
+- [UI Builder](#ui-builder)
+  - [1. Dialog](#dialog)
+  - [2. Drawer](#drawer)
+- [Using Custom UI](#using-custom-ui)
+
+### ConsentManager
+
+First, you must create an instance of the `Osano` object. This object contains the general
+configuration parameters that will be used throughout the life of the
+application.
+
+```js
+import { Osano, OsanoContext } from '@osano/osano-cmp-react-native'
+
+// ...
+
+<Osano
+    customerId={customerId}
+    configId={configId}
+    hideDisclosures={hideDisclosures}
+    onConfigLoadSuccess={handleConfigLoadSuccess}
+    onConfigLoadFailure={handleConfigLoadFailure}
+    onLangLoadSuccess={handleLangLoadSuccess}
+    onLangLoadFailure={handleLangLoadFailure}
+    setLoggingEnabled={__DEV__} // Control SDK logging
+    overrides={{
+        flavor: flavor ? flavor : undefined,
+        locale: locale ? locale : undefined,
+    }}
+>
+   <YourAppHere>
+</Osano>
+```
+
+Note that the `configId` and `customerId` parameters are not optional, and must match the values of your configuration on the [Osano website](https://my.osano.com).
+
+To associate an external user identifier with the stored consent record, use `extUsrData`. This identifier is essential for
+[Cross-Device Consent](https://docs.osano.com/hc/en-us/articles/22472143433364-Cross-Domain-and-Cross-Device-Consent).
+
+By providing the same ID across devices and platforms (e.g., web and mobile), the SDK can look up and apply the user’s existing consent record, ensuring consistency across environments. For more internal details, see our [Cross-Device Consent Lookups documentation](https://osano.atlassian.net/wiki/spaces/CMPM/pages/604078081/Cross-Device+Consent+Lookups).
+
+> **_Important considerations_**
+>
+> - SDK behavior: All Osano SDKs will always record `extUsrData`. This is required for cross-device consent to function properly.
+> - Web CMP behavior: The Web CMP will not record `extUsrData` unless cross-device consent is explicitly enabled in your configuration. If cross-device consent is not enabled, the parameter will be ignored.
+>
+> Because of this distinction, developers should not expect extUsrData to have any effect in the Web CMP unless cross-device consent is turned on.
+
+#### Logging Configuration
+
+The SDK includes built-in logging for debugging. Use `setLoggingEnabled={__DEV__}` to enable logging in development and disable it in production. All logs are prefixed with `[OsanoSDK]`.
+
+You can use the `OsanoContext` to access the `ConsentManager` object:
+
+```js
+const {
+	clearConsent,
+	getConsent,
+	getDeviceId,
+	locale,
+	setLocale,
+	showBanner,
+	showDrawer,
+	isReady,
+} = React.useContext(OsanoContext);
+```
+
+### UI Builder
+
+Now that you have created an instance of the `ConsentManager`, you can
+use it to create and show consent messages in your application. There
+are two types of dialogues available to show in the SDK, and (depending on the geo-location of your end-user) the UI for each will look different. This is due to legal requirements that are in place for the end-user's geo-location. Rest assured, these UI differences are intentional and necessary to maintain legal compliance for the location of your users.
+
+#### Display Modes
+
+The UI may de shown in 2 different ways:
+
+##### Dialog
+
+The Dialog View Controller allows you to show a consent message and the
+required data storage preferences based on the country the device is in.
+The SDK takes care of figuring out which consent variant must be shown
+based on the device's locale.
+
+To create the dialogue and show it, use the `showDrawer` method from the `OsanoContext`:
+
+```js
+<Pressable onPress={showDrawer}>
+	<Text>Show Categories Dialog</Text>
+</Pressable>
+```
+
+:::note
+
+The dialog (depending on the end-user's geo-location) may have an automatic timeout, which will grant consent upon closure. This is normal functionality for specific global regions.
+
+:::
+
+:::caution Declined to Consent
+
+If a the completion callback notifies you that the end-user declined to consent, this **does not mean** they _denied_ consent. It simply means that they _**did not make a selection**_.
+
+The Drawer UI will not allow the user to dismiss the modal without making a selection, but the Dialog UI (in some geo-locations) will allow the user to dismiss the modal without making a selection. This is why it is important to check the `categories` array in the completion callback to determine if the user has actually declined to consent.
+
+:::
+
+##### Drawer
+
+The Drawer View Controller allows you to display all consent
+categories using a built-in UI. In this dialogue, the user can choose to
+enable or disable any of the consent categories.
+To user the view controller and show it, use the method `showBanner`
+
+```js
+<Pressable onPress={showBanner}>
+	<Text>Show Concent Banner</Text>
+</Pressable>
+```
+
+### Using Custom Implementation
+
+If the SDK's built-in UI and implementation does not fit your requirements, you can use the
+`ConsentManager`'s APIs and integrate them to your own app's UI:
+
+```js
+const consentManager = useRef<ConsentManager>(new ConsentManager());
+const [_state, dispatch, getState, addMiddleware, removeMiddleware] =
+		useThunkReducer<OsanoState, OsanoAction>(
+			reducer,
+			{ configId, customerId },
+			init,
+			[],
+		);
+return(
+    <OsanoPublicContext.Provider value={context}>
+	    {<YourAppHere>}
+	    <ConsentUiBuilder
+		    addMiddleware={addMiddleware}
+		    removeMiddleware={removeMiddleware}
+		    dispatch={dispatch}
+		    getState={getState}
+		    cmp={consentManager}
+		    hideDisclosures={hideDisclosures}
+	    />
+    </OsanoPublicContext.Provider>
+)
+```
+
+To save (locally and remotely) new consent categories use:
+
+```js
+recordConsent(consentManager.current, ConsentCategory.ESSENTIAL); //ESSENTIAL, ANALYTICS, MARKETING, PERSONALIZATION, OPT_OUT
+```
+
+To get the list of consented categories (local storage):
+
+```js
+let consentedArray = consentManager.current.consent;
+let consentedString = consentedArray.join(', ');
+console.log(consentedString);
+```
+
+To get whether the user has already gone through the consent process:
+
+```js
+let userConsented = consentManager.current.consent.length > 0;
+```

package/README.md

@@ -1,269 +1,3 @@
-# Osano CMP React Native
+# Osano CMP SDK for React Native
 
-## Necessary Software Setup
-
-1. Xcode
-1. Android Studio
-1. Xcode command-line tools
-1. Node
-
-### Corepack
-
-This project uses `corepack` to manage and link dependencies. To install `corepack`, run the following commands:
-
-```shell
-corepack enable
-corepack install # installs yarn
-```
-
-## Running Locally
-
-The repo is made up of a root folder and 2 important sub folders. The first is `packages`, which is the actual SDK. The second is `examples`, which includes different implementations of the SDK in a test app to demonstrate and test integration.
-
-From the root folder, run the following:
-
-```shell
-corepack yarn install
-corepack yarn prepare
-cd example/ios && pod install && cd ../..
-cd example/ios && echo export NODE_BINARY=$(command -v node) > .xcode.env && cd ../.. # do once
-cp example/.env.example example/.env # do once
-corepack yarn example android # or ios
-
-# alternatively
-cd example && corepack yarn start android # or ios
-```
-
-### Specifying run destination
-
-**iOS**
-
-`corepack yarn example ios --simulator "iPhone 15 Pro"`
-
-**Android**
-
-`// TODO`
-
-## Running Tests
-
-Testing should be done through both the example integration and the package itself.
-
-### Testing the package
-
-1. From the `packages/osano-comp-react-native` folder run the following. This specifically runs the tests associated with the main package
-
-```shell
-npm test /src/__tests__
-```
-
-1. In order to test all test files in the package, including IAB, run the following from the `packages/osano-comp-react-native` folder
-
-```shell
-npm test
-```
-
-### Testing the examples
-
-#### Build the test applications from local builds
-
-- iOS
-
-1. Run the iOS application locally via `yarn example ios`
-1. Open the Derived Data in your XCode folder `~/Library/Developer/XCode/DerivedData`
-1. One of the folders in the `DerivedData` folder will contain a `Build` folder
-1. Open `Build/Products/<device-type>`
-1. The .app file will be `OsanoCMPExample` with a file type `Application`
-
-- Android
-
-1. Run the android example application locally via `yarn example android`
-1. In `Android Studio` under `Project` open `app/build/outputs/apk/<release-or-debug>/` to get the apk file
-
-Both files can be sent to coworkers with an ios simulator or android emulator to run for testing
-
-## Troubleshooting
-
-1.  If the `run` command fails saying there is no development project, make sure to open the relevant simulator/emulator before running.
-1.  If there are significant errors citing duplicates, it is likely you ran `npm i` in the packages folder. These files should be removed via `rm -rf node_modules` in the `packages/osano-cmp-react-native` folder from the command line
-1.  For initial developing and testing make sure you have a relatively recent simulator on iOS and emulator on Android. Old devices running old OS can cause unnecessary issues
-1.  Building the iOS example from Xcode might result in a `Command PhaseScriptExecution failed with a nonzero exit code`. This is caused by a missing `.xcode.env` file that contains an entry for NODE_PATH. Resolve by running `echo export NODE_BINARY=$(command -v node) > .xcode.env` from the `example/ios` directory.
-
-=======
-
-The Osano ConsentSDK for iOS is a native framework that integrates with the Consent Management Platform on the [Osano Website](https://my.osano.com). It is necessary to have an account, and a Cookie Consent configuration created and published in order for this SDK to be able to record end-user consents.
-
-### Installation
-
----
-
-We use NPM to manage and install the SDK package.
-
-1. At the top level of your project run `npm install @osano/osano-cmp-react-native`
-
-#### Native iOS installation
-
-NPM uses cocoapods to install the native iOS portion of modules[CocoaPods](https://guides.cocoapods.org/)
-
-1. Install Cocoapods using [Cocoapods - Getting Started](https://guides.cocoapods.org/using/getting-started.html).
-1. Run `pod install` from inside the iOS folder in your project
-
-#### Native Android installation
-
-1. Run a gradle sync after `@osano/osano-cmp-react-native` has been added to your package manager
-
-### Integration
-
-## How do I use it?
-
-- [ConsentManager](#consentmanager)
-- [UI Builder](#ui-builder)
-  - [1. Dialog](#dialog)
-  - [2. Drawer](#drawer)
-- [Using Custom UI](#using-custom-ui)
-
-### ConsentManager
-
-First, you must create an instance of the `Osano` object. This object contains the general
-configuration parameters that will be used throughout the life of the
-application.
-
-```js
-import { Osano, OsanoContext } from '@osano/osano-cmp-react-native'
-
-// ...
-
-const
-<Osano
-    customerId={customerId}
-    configId={configId}
-    hideDisclosures={hideDisclosures}
-    onConfigLoadSuccess={handleConfigLoadSuccess}
-    onConfigLoadFailure={handleConfigLoadFailure}
-    onLangLoadSuccess={handleLangLoadSuccess}
-    onLangLoadFailure={handleLangLoadFailure}
-    overrides={{
-        flavor: flavor ? flavor : undefined,
-        locale: locale ? locale : undefined,
-    }}
->
-   <YourAppHere>
-</Osano>
-```
-
-Note that the `configId` and `customerId` parameters are not optional, and must match the values of your configuration on the [Osano website](https://my.osano.com).
-
-You can use the `OsanoContext` to access the `ConsentManager` object:
-
-```js
-const {
-	clearConsent,
-	getConsent,
-	getDeviceId,
-	locale,
-	setLocale,
-	showBanner,
-	showDrawer,
-	isReady,
-} = React.useContext(OsanoContext);
-```
-
-### UI Builder
-
-Now that you have created an instance of the `ConsentManager`, you can
-use it to create and show consent messages in your application. There
-are two types of dialogues available to show in the SDK, and (depending on the geo-location of your end-user) the UI for each will look different. This is due to legal requirements that are in place for the end-user's geo-location. Rest assured, these UI differences are intentional and necessary to maintain legal compliance for the location of your users.
-
-#### Display Modes
-
-The UI may de shown in 2 different ways:
-
-##### Dialog
-
-The Dialog View Controller allows you to show a consent message and the
-required data storage preferences based on the country the device is in.
-The SDK takes care of figuring out which consent variant must be shown
-based on the device's locale.
-
-To create the dialogue and show it, use the `showDrawer` method from the `OsanoContext`:
-
-```js
-<Pressable onPress={showDrawer}>
-	<Text>Show Categories Dialog</Text>
-</Pressable>
-```
-
-:::note
-
-The dialog (depending on the end-user's geo-location) may have an automatic timeout, which will grant consent upon closure. This is normal functionality for specific global regions.
-
-:::
-
-:::caution Declined to Consent
-
-If a the completion callback notifies you that the end-user declined to consent, this **does not mean** they _denied_ consent. It simply means that they _**did not make a selection**_.
-
-The Drawer UI will not allow the user to dismiss the modal without making a selection, but the Dialog UI (in some geo-locations) will allow the user to dismiss the modal without making a selection. This is why it is important to check the `categories` array in the completion callback to determine if the user has actually declined to consent.
-
-:::
-
-##### Drawer
-
-The Drawer View Controller allows you to display all consent
-categories using a built-in UI. In this dialogue, the user can choose to
-enable or disable any of the consent categories.
-To user the view controller and show it, use the method `showBanner`
-
-```js
-<Pressable onPress={showBanner}>
-	<Text>Show Concent Banner</Text>
-</Pressable>
-```
-
-### Using Custom Implementation
-
-If the SDK's built-in UI and implementation does not fit your requirements, you can use the
-`ConsentManager`'s APIs and integrate them to your own app's UI:
-
-```js
-const consentManager = useRef<ConsentManager>(new ConsentManager());
-const [_state, dispatch, getState, addMiddleware, removeMiddleware] =
-		useThunkReducer<OsanoState, OsanoAction>(
-			reducer,
-			{ configId, customerId },
-			init,
-			[],
-		);
-return(
-    <OsanoPublicContext.Provider value={context}>
-	    {<YourAppHere>}
-	    <ConsentUiBuilder
-		    addMiddleware={addMiddleware}
-		    removeMiddleware={removeMiddleware}
-		    dispatch={dispatch}
-		    getState={getState}
-		    cmp={consentManager}
-		    hideDisclosures={hideDisclosures}
-	    />
-    </OsanoPublicContext.Provider>
-)
-```
-
-To save (locally and remotely) new consent categories use:
-
-```js
-recordConsent(consentManager.current, ConsentCategory.ESSENTIAL); //ESSENTIAL, ANALYTICS, MARKETING, PERSONALIZATION, OPT_OUT
-```
-
-To get the list of consented categories (local storage):
-
-```js
-let consentedArray = consentManager.current.consent;
-let consentedString = consentedArray.join(', ');
-console.log(consentedString);
-```
-
-To get whether the user has already gone through the consent process:
-
-```js
-let userConsented = consentManager.current.consent.length > 0;
-```
+Visit the [Developer Docs](https://developers.osano.com/cmp/react-native/) to learn more about installation and usage.

package/android/src/main/java/com/OsanoCMPSDK/OsanoCMPSDKModule.kt

@@ -1,14 +1,19 @@
 package com.osano.cmp.sdk
 
 import com.facebook.react.bridge.ReactApplicationContext
-import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.Promise
 import android.content.Context
 import android.provider.Settings
+import android.preference.PreferenceManager
 import java.util.UUID
 
-class OsanoCMPSDKModule(reactContext: ReactApplicationContext) :
+// New Architecture support
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.module.annotations.ReactModule
+
+@ReactModule(name = OsanoCMPSDKModule.NAME)
+class OsanoCMPSDKModule(private val reactContext: ReactApplicationContext) :
   ReactContextBaseJavaModule(reactContext) {
 
   override fun getName(): String {
@@ -43,6 +48,46 @@ class OsanoCMPSDKModule(reactContext: ReactApplicationContext) :
         promise.resolve(null)
     }
 
+    @ReactMethod
+    fun setStorageToDefault(key: String?, value: String?, promise: Promise) {
+        val appContext = this.reactApplicationContext.applicationContext
+        val defaultSharedPreferences = PreferenceManager.getDefaultSharedPreferences(appContext)
+        val editor = defaultSharedPreferences.edit()
+        editor.putString(key, value)
+        editor.apply()
+        promise.resolve(value)
+    }
+
+    @ReactMethod
+    fun setIntStorageToDefault(key: String?, value: Int, promise: Promise) {
+        val appContext = this.reactApplicationContext.applicationContext
+        val defaultSharedPreferences = PreferenceManager.getDefaultSharedPreferences(appContext)
+        val editor = defaultSharedPreferences.edit()
+        editor.putInt(key, value)
+        editor.apply()
+        promise.resolve(value)
+    }
+
+    @ReactMethod
+    fun setBoolStorageToDefault(key: String?, value: Boolean, promise: Promise) {
+        val appContext = this.reactApplicationContext.applicationContext
+        val defaultSharedPreferences = PreferenceManager.getDefaultSharedPreferences(appContext)
+        val editor = defaultSharedPreferences.edit()
+        editor.putBoolean(key, value)
+        editor.apply()
+        promise.resolve(value)
+    }
+
+    @ReactMethod
+    fun clearStorageFromDefault(key: String?, promise: Promise) {
+        val appContext = this.reactApplicationContext.applicationContext
+        val defaultSharedPreferences = PreferenceManager.getDefaultSharedPreferences(appContext)
+        val editor = defaultSharedPreferences.edit()
+        editor.remove(key)
+        editor.apply()
+        promise.resolve(null)
+    }
+
     @ReactMethod
     fun getDeviceId(promise: Promise) {
         // Get a unique vendor ID for the android device
@@ -66,7 +111,15 @@ class OsanoCMPSDKModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    override fun getConstants(): MutableMap<String, Any> {
+        val appId = reactContext.packageName
+        val isOfficialSample = SAMPLE_APP_IDS.contains(appId)
+        return hashMapOf("IS_OFFICIAL_SAMPLE" to isOfficialSample)
+    }
+
   companion object {
     const val NAME = "OsanoCmpSdk"
+
+    private val SAMPLE_APP_IDS = setOf("com.OsanoCMPExample")
   }
 }