This is a Beta product.
Overview
The Osano iOS SDK allows developers a simple way to integrate consent capture and consent preferences into their iOS applications. In contrast to our web solution, the iOS SDK captures only consent records and does not tattle or actively block libraries from loading. Consent record and preference changes are stored remotely through our API and on the device for 365 days. If a user deletes the application, their preferences are deleted as well.
Features Provided
- UI for end-users
- Screens:
- Banner
- Manage Storage Preferences
- Translation
- Detect language and apply the legally required regional consent options
- Consent capture
Note: Currently the iOS SDK only supports fully native components and will not pass consent preferences to any embedded web views.
Running the Sample Application
- Extract the zip file contents provided by Osano’s Sales & Support team.
- After extracting the zip file contents, cd into the ConsentAppObjC or ConsentAppSwiftdirectory and install Cocoapods.
- In the same directory, run pod install
- Start Xcode, and open the .xcworkspace file from the ConsentAppObjC or ConsentAppSwift directory.
- Select a device in Xcode and run it.
Install Cocoapods using "Cocoapods - Getting Started"
In your project's Podfile add a source for our Cocoapods specs repo.
source "https://github.com/osano/cocoapods-specs.git"<br>
Within your target add the OsanoConsentManagerSDK and version as a referenced pod.
pod 'OsanoConsentManagerSDK', '2.1.4'<br>
Your project's Podfile should look similar to the one below.
platform :ios, '10.0'source "https://github.com/osano/cocoapods-specs.git"target 'MyApp'do use_frameworks!<br>
pod 'OsanoConsentManagerSDK', '2.1.4'End<br>
Showing the Consent Banner Dialog (Cookie Popup)
The consent banner can be displayed in a modal, full screen, or bottom sheet.
The SDK provides the ability to force a language. For a list of consent dialog regions based on country, please visit the documentation here.
Showing the Storage Preferences Dialog (The Drawer)
The storage preference UI can be displayed in a modal, full screen, or bottom sheet.
The SDK provides the ability to adjust the colors for both the banner and drawer. Set the data storage policy link to your own valid policy URL. It’s currently set to google.com for testing purposes.
**Note** - When updating preferencing and accepting changes, the latest preferences should persist the next time the user opens the preferences drawer.
Recording Consents
- The following values must be available in order for consent records to process correctly:
- customerId - This can be retrieved via your consent manager configuration in the web app or via Osano customer support.
- configId - Available in your consent manager configuration in the Osano web application (Both the config ID and the customer ID are included in your osano.js src="https://cmp.osano.com/222cpvRm9bbsqngN/22222aa0-c222-2222-81d2-7671fc6e8479/osano.js")
- sample: "11111111-2222-3333-4444-555555555555"
-
- consentingDomain - Optional value associated domain that this consent should be associated with.
- Max characters - 256
- consentUiBuilder.countryCode = "us" - Optional character country code. For a list of consent dialog regions based on country, please visit https://docs.osano.com/article/89-consent-dialog-format-by-region.
- Ensures the correct variant is displayed in accordance to the laws of the respective country.
- If not provided the SDK will use the device locale
- consentingDomain - Optional value associated domain that this consent should be associated with.
- IMPORTANT: Please avoid changing the logic for storing a consent listener. This method helps record consents properly.
CCPA Opt-Out Mode
- In order to provide a link to Collection Preferences, bind the storage preferences dialog to a link.
- In order to opt users into certain preferences, you should be able to call the storeConsent object.
How do I use it?
ConsentManager
First, you must create an instance of the `ConsentManager` object. This object contains the general configuration parameters that will be used throughout the life of the Application.
let consentManager = ConsentManager(customerId: "my_customer_id", configId: "my_config_id", consentingDomain: "my_constaint_domain")
Note that the configId and customerId parameters are not optional.
Built-in 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
UI Builder
The dialogue UI can be personalized via the following builder
Parameters:
letConsentUiBuilder = ConsentUiBuilder(backgroundColor: .white, textColor: .black, accentColor: .purple, positiveColor: .blue, positiveTextColor: .white, negativeColor: .black, negativeTextColor: .white, subButtonColor: .blue, dataStoragePolicyUrl: "http://www.google.com", countryCode: nil)
To override the country locale that is used to show the consent variant, use `countryCode` in the builder:
consentUiBuilder.countryCode = "us"
Display Modes
The UI may be shown in 2 different ways:
Variants
The Variant 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. You can choose the presentation type with the PresentationType enum:
public enum PresentationType: Int {
case modal
case fullScreen
case bottomSheet
}
To create the dialogue and show it, use:
let type = ConsentUiBuilder.PresentationType.fullScreen
consentUiBuilder.showVariantViewController(presenterViewController: self,
type: type)
Categories ViewController
The categoriesViewController 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.
guardlet viewController = consentUiBuilder.categoriesViewController else { return }let customNavigationController = UINavigationController(rootViewController: viewController)customNavigationController.modalPresentationStyle = .automaticconsentUiBuilder.hideNavigationBarFromCategoriesViewController = truepresent(customNavigationController, animated: true, completion: nil)
In the example the user is embedding the view controller inside a UINavigationController, to hide the navigation the consentUiBuilder has a parameter that can be used:
consentUiBuilder.hideNavigationBarFromCategoriesViewController = true
Using Custom UI
If the SDK's built-in UI does not fit your requirements, you can use the ConsentManager APIs and integrate them to your own app's UI:
To save (locally and remotely) new consent categories use:
Objective-C:
self.consentManager = [[ConsentManager alloc] initWithCustomerId: @"my_customer_id"
configId: @"my_config_id"
consentingDomain: @"my_constaint_domain"];
OsanoCategoryObject *categoryEssential = [OsanoCategoryObject factoryWithCategory: OsanoCategoryEssential];
OsanoCategoryObject *categoryMarketing = [OsanoCategoryObject factoryWithCategory: OsanoCategoryMarketing];
OsanoCategoryObject *categoryAnalytics = [OsanoCategoryObject factoryWithCategory: OsanoCategoryAnalytics];
OsanoCategoryObject *categoryPersonalization = [OsanoCategoryObject factoryWithCategory: OsanoCategoryPersonalization];
OsanoCategoryObject *categoryOpt = [OsanoCategoryObject factoryWithCategory: OsanoCategoryOpt_out];
NSArray *consentArray = [NSArray arrayWithObjects: categoryEssential, categoryMarketing, categoryAnalytics, categoryPersonalization, categoryOpt, nil];
[consentManager consentWithObjectCategories: consentArray];
Swift:
consentManager.consent(categories: [.analytics,
.essential,
.marketing,
.personalization,
.opt_out])
To fetch the list of available disclosures based on your customer id and
config id:
Objective-C:
[consentManager fetchDisclosuresWithResult:^(NSArray<Disclosure *> *disclosures, BOOL error) {
if (error) {
NSLog(@"Error");
return;
}
for (Disclosure *disclosure in disclosures) {
NSLog(@"%@", disclosure.categoryName);
}
}];
Swift:
consentManager.fetchDisclosures { (disclosures, error) in
guard error == false else { return }
print(disclosures)
}
To get the list of consented categories (local storage):
Objective-C:
NSArray *consentedArray = [self.consentManager userConsentedCategories];
NSString *consentedString = [consentedArray componentsJoinedByString:@", "];
NSLog(@"%@", consentedString);<br>
Swift:
guard let consentedArray = consentManager.userConsentedCategories() as? [String] else { return }
let consentedString = consentedArray.joined(separator: ", ")
print(consentedString)
To get whether the user has already gone through the consent process:
Objective-C<br>
Blocking Libraries
You should map your libraries to the consent categories. When a user denies consent, those libraries should stop sending data. In addition, the next time the app is closed and opens, those libraries should not initialize.
Upon request, we can provide our recommendations on what category your libraries map to.
Marketing Communications Opt-Outs
When a user denies consent for marketing, you should opt them out of your marketing communications as well.
Offline behavior
If the end-user is offline when making
Updating Library Versions
In your projects Podfile, update the semantic version to the new version you wish to use.
pod 'OsanoConsentManagerSDK', '2.0.10'
is changed to
pod 'OsanoConsentManagerSDK', '2.1.0'
From the command line where your Podfile is, update the Pods using the Cocoapods update command.
{replace0}gt; pod update
This will update the library to the newest version.
If the application is still using the old library after the update, you may need to clean your Cocoapods cache. In your application directory where your Podfile is, run the following commands:
{replace0}gt; rm -rf Podfile.lock Pods/<br>{replace0}gt; pod cache clear --all
This will fully clear the local cache and force a download of the Pods in the Podfile.