iOS

The AppConsentKit SDK brings AppConsent to your native iOS app. In this guide, you'll learn how to integrate it in your application.

Adding AppConsentKit to your application

Reminder : We offer two versions of the CMP :

Xchange is free of charge, Premium is a paid version.

-> Download the right SDK (Premium or Xchange) according to your choice.

Downloading the SDK

Download the version 2.3.9. The download link you need depends on your version of Xcode

Premium
XChange (Free)
Premium

Xcode version

Link

Xcode 11.0 and above

Download here

From Xcode 10.2 to Xcode 10.3

Download here

Below Xcode 10.2

Download here

XChange (Free)

Xcode version

Link

Xcode 11.0 and above

Download here

From Xcode 10.2 to Xcode 10.3

Download here

Below Xcode 10.2

Download here

Important! If you were using a previous version of the SDK (1.7 or earlier) you will have to create a new notice, and update some settings in your assets. Please, read this section to learn more

Add the SDK to your project

After downloading the SDK, follow the steps below to add it to your application.

  • Drag and drop the AppConsentKit.framework file in your Xcode project. In the General tab of you application target, make sure the Framework has been added in Frameworks, Libraries and Embedded Content.

Premium
XChange
Premium
XChange
  • ⚠️ For Objective-C projects, in your app build settings, search Always Embed Swift Standard Libraries and set it to Yes

Build settings for Objective-C projects

Add build phases

To be able to export your archive and submit to the AppStore, you'll need to add two build phases to your project in your target Build phases tab.

  • Before the Embed Frameworks phase, add a new phase as a Run script and past the following script:

Premium
XChange
Premium
if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphoneos" ]; then
cp "${SCRIPT_INPUT_FILE_0}/AppConsentKit" "${BUILD_DIR}/AllAppConsentKit"
lipo -remove "i386" -remove "x86_64" "${SCRIPT_INPUT_FILE_0}/AppConsentKit" -output "${SCRIPT_INPUT_FILE_0}/AppConsentKit"
fi
XChange
if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphoneos" ]; then
cp "${SCRIPT_INPUT_FILE_0}/AppConsentKitXChange" "${BUILD_DIR}/AllAppConsentKit"
lipo -remove "i386" -remove "x86_64" "${SCRIPT_INPUT_FILE_0}/AppConsentKitXChange" -output "${SCRIPT_INPUT_FILE_0}/AppConsentKitXChange"
fi

In the same phase, add as an Input File the path to the AppConsent framework.

Premium
XChange
Premium
XChange
  • Add a second build phase right after the Embed Frameworks phase with the following script:

Premium
XChange
Premium
if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphoneos" ]; then
mv "${BUILD_DIR}/AllAppConsentKit" "${SCRIPT_INPUT_FILE_0}/AppConsentKit"
fi
XChange
if [ "$EFFECTIVE_PLATFORM_NAME" == "-iphoneos" ]; then
mv "${BUILD_DIR}/AllAppConsentKit" "${SCRIPT_INPUT_FILE_0}/AppConsentKitXChange"
fi

As for the previous one, add the path to AppConsent as an Input File.

Premium
XChange
Premium
XChange

Using AppConsentKit

The main interface of the AppConsent SDK is the AppConsent class. First, start by importing the SDK in your code.

Premium
XChange
Premium

Swift

Objective-C

import AppConsentKit

#import <AppConsentKit/AppConsentKit.h>

XChange

Swift

Objective-C

import AppConsentKitXChange

#import <AppConsentKitXChange/AppConsentKitXChange.h>

Then as soon as possible in your code, like in your AppDelegate didFinishLaunchingWithOptions method for example, start the SDK. To do so you'll need your notice URL with your version ID that you'll have in the AppConsent back-office. Read this page to get your resource URL.

Swift
Objective-C
Swift
let url = URL(string: "https://my.notice/notice.json")
AppConsent.start(withNoticeUrl: url);
Objective-C
NSURL *url = [NSURL URLWithString:@"https://my.notice/notice.json"];
[AppConsent startWithNoticeUrl:url];

Managing consents

Getting user consents starts by displaying a notice which will prompt the user to configure the use of his data. You should do it as soon as possible in your application lifecycle. To do so, you can present a full page notice or a smaller banner.

Presenting a notice or banner

To present a notice, use the following code.

Swift
Objective-C
Swift
// the mode should depend on your use case
let mode: AppConsentPresentationMode = .automatic
let willAppear: Bool = AppConsent.presentNotice(delegate: aDelegate,
withMode: mode)
Objective-C
// the mode should depend on your use case
AppConsentPresentationMode mode = AppConsentPresentationModeAutomatic
BOOL willAppear = [AppConsent presentNoticeWithDelegate:aDelegate
withMode:mode];

To present a banner, use the following.

Swift
Objective-C
Swift
// the mode should depend on your use case
let mode: AppConsentPresentationMode = .automatic
let willShow: Bool = AppConsent.presentBanner(delegate: aDelegate,
withMode: mode)
Objective-C
// the mode should depend on your use case
AppConsentPresentationMode mode = AppConsentPresentationModeAutomatic
BOOL willShow = [AppConsent presentBannerWithDelegate:self
withMode:mode];

When calling those methods, the SDK can decide not to present the notice for some internal reasons. This is why this method returns a boolean value.

You can use the shouldPresentNotice method of AppConsent before you actually try to present a notice or a banner.

Swift
Objective-C
Swift
if AppConsent.shouldPresentNotice(delegate: delegate) {
// present
}
Objective-C
if ([AppConsent shouldPresentNoticeWithDelegate:delegate]) {
// present
}

Displaying the notice or banner

After you called presentNotice or presentBanner, your delegate is called with an AppConsentCMP object. Use this object to present your notice or banner on a view controller.

Swift
Objective-C
Swift
func appConsentCMPReady(_ cmp: AppConsentCMP) {
cmp.present(onViewController: aViewController)
}
Objective-C
- (void)appConsentCMPReady:(AppConsentCMP *)cmp {
[cmp presentOnViewController:aViewController];
}

About display mode

One parameter when displaying a notice or banner is a value from AppConsentPresentationMode. The possible modes are:

Swift
Objective-C
Swift

Mode

Description

.automatic

The notice or banner will be displayed only if no previous consent has been given. It should be used when you present a notice based on a developer choice.

.userDemand

The notice will be displayed even if a previous consent has been given by the user. It should be used when the notice is displayed after a user action, in your app settings for example. The notice UI and flow will be slightly different and shorter.

.automaticForced

The notice will be displayed like will the automatic mode, with the same UI variations, but it will be displayed every time. It should only be used for development and debug purpose.

Objective-C

Mode

Description

AppConsentPresentationModeAutomatic

The notice or banner will be displayed only if no previous consent has been given. It should be used when you present a notice based on a developer choice.

AppConsentPresentationModeUserDemand

The notice will be displayed even if a previous consent has been given by the user. It should be used when the notice is displayed after a user action, in your app settings for example. The notice UI and flow will be slightly different and shorter.

AppConsentPresentationModeAutomaticForced

The notice will be displayed like will the automatic mode, with the same UI variations, but it will be displayed every time. It should only be used for development and debug purpose.

Delegate basic implementation

Presenting a notice or banner also take a delegate parameter. It is an object conforming to the AppConsentDelegate protocol. Here are the main methods you'll need to implement.

Swift
Objective-C
Swift
// called when the consent has been given
func appConsentDidFinish() {
print("consent did finish")
}
// called in case of error
func appConsentDidFail(_ error: Error) {
print("consent did fail: \(error.localizedDescription)")
}
// the CMP object to present
func appConsentCMPReady(_ cmp: AppConsentCMP) {
cmp.present(onViewController: aViewController)
}
Objective-C
// called when the consent has been given
- (void)appConsentDidFinish {
NSLog(@"AppConsent did finish");
}
// called in case of error
- (void)appConsentDidFail:(NSError *)error {
NSLog(@"AppConsent did fail: %@", error.localizedDescription);
}
// the CMP to present
- (void)appConsentCMPReady:(AppConsentCMP *)cmp {
[cmp presentOnViewController:aViewController];
}

Also, those optionals methods let you know when the notice or banner actually appears and disappears.

Swift
Objective-C
Swift
// for the notice
func appConsentWillAppear() { ... }
func appConsentDidAppear() { ... }
func appConsentWillDisappear() { ... }
func appConsentDidDisappear() { ... }
// for the banner
func appConsentBannerWillAppear() { ... }
func appConsentBannerDidAppear() { ... }
func appConsentBannerWillDisappear() { ... }
func appConsentBannerDidDisappear() { ... }
// this last method lets you know the frame the banner view will use, you can
// use it to adapt your UI, inset a scroll view or collection view, etc.
func appConsentBannerWillResize(frame: CGRect) { ... }
Objective-C
// for the notice
- (void)appConsentWillAppear { ... }
- (void)appConsentDidAppear { ... }
- (void)appConsentWillDisappear { ... }
- (void)appConsentDidDisappear { ... }
// for the banner
- (void)appConsentBannerWillAppear { ... }
- (void)appConsentBannerDidAppear { ... }
- (void)appConsentBannerWillDisappear { ... }
- (void)appConsentBannerDidDisappear { ... }
// this last method lets you know the frame the banner view will use, you can
// use it to adapt your UI, inset a scroll view or collection view, etc.
- (void)appConsentBannerWillResizeWithFrame:(CGRect)frame { ... }

Managing the user's country

By default the AppConsent SDK will only present a notice on automatic mode only if the user's device is set to a GDPR country. You can chose to ignore the user's device country and display a notice anyway by implementing the optional ignoreCountry() method of AppConsentDelegate.

Swift
Objective-C
Swift
func ignoreCountry() -> Bool {
return true
}
Objective-C
- (BOOL)ignoreCountry {
return YES;
}

Reading consents values

AppConsent exposes properties to read the consent values described by the IAB framework.

Swift
Objective-C
Swift
let cmpPresent = AppConsent.iabCmpPresent
let subjectToGDPR = AppConsent.iabSubjectToGDPR
let consentString = AppConsent.iabConsentString
let parsedVendors = AppConsent.iabParsedVendors
let parsedPurposes = AppConsent.iabParsedPurposes
Objective-C
BOOL cmpPresent = [AppConsent iabCmpPresent];
BOOL subjectToGDPR = [AppConsent iabSubjectToGDPR];
NSString *consentString = [AppConsent iabConsentString];
NSString *parsedVendors = [AppConsent iabParsedVendors];
NSString *parsedPurposes = [AppConsent iabParsedPurposes];

You can also read the authorization for a given IAB vendor or purpose using the following methods:

Swift
Objective-C
Swift
let vendor = AppConsent.isIABVendorAllowed(withId: 42)
let purpose = AppConsent.isIABPurposeAllowed(.measurement)
Objective-C
BOOL vendor = [AppConsent isIABVendorAllowedWithId:42];
BOOL purpose = [AppConsent isIABPurposeAllowed:IabPurposeMeasurement];

Alternatively and as described in the IAB specification (see CMP Internal structure) the consents values are stored in UserDefaults with the following keys:

"IABConsent_SubjectToGDPR"
"IABConsent_CMPPresent"
"IABConsent_ConsentString"
"IABConsent_ParsedVendorConsents"
"IABConsent_ParsedPurposeConsents"

So you can read the consents values for IAB vendors and purposes as follow:

Swift
Objective-C
Swift
let vendors = UserDefaults.standard.string(forKey: "IABConsent_ParsedVendorConsents")
Objective-C
NSString *parsedVendors = [[NSUserDefaults standardUserDefaults] stringForKey:@"IABConsent_ParsedVendorConsents"];

Managing geolocation consents

The use of geolocation for advertising or other purposes has some dedicated methods. Those purposes has to be defined and linked to you notice version id in the AppConsent back-office. Once it is defined, it will appear in the notice itself, but you can prompt the user for those purposes through a banner or a dedicated full screen notice.

Presenting a notice or banner

To present a full screen notice use the code below.

Swift
Objective-C
Swift
// the mode should depend on your use case
let mode: AppConsentPresentationMode = .automatic
AppConsent.presentGeoNotice(delegate: aDelegate, withMode: mode)
Objective-C
// the mode should depend on your use case
AppConsentPresentationMode mode = AppConsentPresentationModeAutomatic
[AppConsent presentGeoNoticeWithDelegate:aDelegate withMode:mode];

To present a banner use the following.

Swift
Objective-C
Swift
// the mode should depend on your use case
let mode: AppConsentPresentationMode = .automatic
AppConsent.presentGeoBanner(delegate: aDelegate, withMode: mode)
Objective-C
// the mode should depend on your use case
AppConsentPresentationMode mode = AppConsentPresentationModeAutomatic
[AppConsent presentGeoBannerWithDelegate:aDelegate withMode:mode];

You can use the shouldPresentGeolocationNotice method of AppConsent before you actually try to present a notice or a banner.

Swift
Objective-C
Swift
if AppConsent.shouldPresentGeolocationNotice(delegate: delegate) {
// present
}
Objective-C
if ([AppConsent shouldPresentGeolocationNoticeWithDelegate:delegate]) {
// present
}

Setting previously collected consents

If you already stored user consents before you actually integrated AppConsentKit you can set this consent directly.

To do so you need to know the purpose ids of the extra purposes you use. You can find it in the AppConsent back-office or by contacting your SFBX representative.

Swift
Objective-C
Swift
let geoConsents = ["purpose-id-1": true, "purpose-id-2": false]
AppConsent.setGeolocPurposesAuthorization(geoConsents) { err in
print(err?.localizedDescription ?? "set geo purposes auth: no error")
}
Objective-C
NSDictionary *geoConsents = @{@"purpose-id-1": @YES, @"purpose-id-2": @NO};
[AppConsent setGeolocPurposesAuthorization:geoConsents completion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Set extra purposes error: %@", error.localizedDescription);
}
}];

Delegate methods for geolocation purposes

The delegate object used by methods managing geolocation purposes is an instance of AppConsentGeolocationConsentDelegate, which itself conforms to AppConsentDelegate.

So in short, if you want to manage consent for geolocation for advertising, just implement AppConsentGeolocationConsentDelegate which adds two methods compared to AppConsentDelegate.

Swift
Objective-C
Swift
func appConsentGeolocationConsentReceived() {
print("geoloc consent received")
}
func appConsentGeolocationConsentFailed(_ error: Error) {
print("geoloc consent failed \(error.localizedDescription)")
}
Objective-C
- (void)appConsentGeolocationConsentReceived {
NSLog(@"geoloc consent received");
}
- (void)appConsentGeolocationConsentFailed:(NSError *)error {
NSLog(@"geoloc consent failed: %@", error.localizedDescription);
}

In addition of those methods, the notice calls the same methods than the standard notice, and the banner calls the same methods than the standard banner.

Swift
Objective-C
Swift
func appConsentWillAppear() { ... }
func appConsentDidAppear() { ... }
func appConsentWillDisappear() { ... }
func appConsentDidDisappear() { ... }
func appConsentBannerWillAppear() { ... }
func appConsentBannerDidAppear() { ... }
func appConsentBannerWillDisappear() { ... }
func appConsentBannerDidDisappear() { ... }
func appConsentBannerWillResize(frame: CGRect) { ... }
Objective-C
- (void)appConsentWillAppear { ... }
- (void)appConsentDidAppear { ... }
- (void)appConsentWillDisappear { ... }
- (void)appConsentDidDisappear { ... }
- (void)appConsentBannerWillAppear { ... }
- (void)appConsentBannerDidAppear { ... }
- (void)appConsentBannerWillDisappear { ... }
- (void)appConsentBannerDidDisappear { ... }
- (void)appConsentBannerWillResizeWithFrame:(CGRect)frame { ... }

Reading the state for geolocation purposes

As explained above, the purpose for geolocation must be defined in our back-office. This is what we call an extra purpose. To get the authorization status, see the section Reading the authorizations for extra purposes and extra vendors.

Managing your list of vendors

Limiting the number of vendors from the IAB Global Vendor List

If your notice is linked to the Global Vendor List, you can limit the number of vendors displayed in your notice.

To do so, add pubVendors json in the Configuration view of your notice on the Back Office as following

{
"publisherVendorsVersion": 1,
"globalVendorListVersion": 42,
"updatedAt": "2018-10-15T00:00:00Z",
"vendors": [
{
"id": 124
}
]
}

Read this section for more information.

Extra purposes and extra vendors

If the AppConsent back-office lets you define your own extra purposes, you can also define extra vendors, to be attached to those purposes.

To do so, add extraVendors json in the Configuration view of your notice on the Back Office as following

To link the vendors defined in the file with your extra purpose, you'll need to know the id of your extra purposes. You can find it in the gvl file : https://vendorlist.consensu.org/v-XXX/vendorlist.json (replace XXX by your GVL number version), or ask your SFBX representative.

{
"vendorListVersion":1,
"lastUpdated":"2018-10-15T00:00:00Z",
"extraVendors": [
{
// This one comes from the GVL
"id": "IdFromGvl",
"name": "My Vendor",
"policyUrl": "https://some.policy-url.com",
"extraPurposeIds": [
"purposeId"
]
},
{
// This one does not come from the GVL, its id is its name
"id": "My other vendor",
"name": "My other vendor",
"policyUrl": "https://some.other-policy-url.com",
"extraPurposeIds": [
"purposeId"
]
}
{
// This one does will not have a switch button, but the switch will be exposed for the global purpose
"id": "My other vendor",
"name": "My other vendor",
"policyUrl": "https://some.other-policy-url.com",
"notConsentablePurposeIds": [
"purposeId"
]
}
]
}

If you use notConsentablePurposeIds, the vendors will not have any switch and the purpose will be exposed like the capture bellow. The consent is propagated for all vendors.

Read this section for more information.

Reading the authorizations for extra purposes and extra vendors

AppConsent provides two methods. One to determine if an extra purpose has been allowed by the user, the other to know if an extra vendor inside an extra purpose has been allowed.

Swift
Objective-C
Swift
ppConsent.isExtraPurposeAllowed(forId: "purpose-id")
AppConsent.isExtraVendorAllowed(forId: "vendor-id", forExtraPurposeWithId: "purpose-id")
Objective-C
BOOL purposeAllowed = [AppConsent isExtraPurposeAllowedForId:@"purpose-id"];
BOOL vendorAllowed = [AppConsent isExtraVendorAllowedForId:@"vendor-id" forExtraPurposeWithId:@"purpose-id"];

Synchronizing data

The list of purposes and vendors relies on the Global Vendor List as specified in the IAB framework. Your notice itself relies on a specific version of that vendor list which can be updated. In that case, the notice should be presented to the user again, thus synchronizing the local data is important.

Also, since your notice can share consents between different apps for the same user through its scope, the consents values can change from one app launch to another.

Synchronizing data is made through the following method.

Swift
Objective-C
Swift
AppConsent.synchronize { synchronized, error in
print("synchronized: \(synchronized), with error? \(error?.localizedDescription ?? "no error")")
// present will be true if the version of the vendor list has been updated.
let present: Bool = AppConsent.shouldPresentNotice
}
Objective-C
[AppConsent synchronizeWithCompletion:^(BOOL synchronized, NSError * _Nullable error) {
NSLog(@"synchronized: %i, with error? %@",
synchronized,
error != nil ? [error localizedDescription] : @"no error");
}];

The synchronized parameter in the completion closure can be false even without any error. For example, if the user never gave his consent, there is no data to sync and synchronized will be false.

You can present the notice (if needed) before you synchronise AppConsent to keep the presentation process synchronous, or in the completion block of the synchronize method. But keep in mind that your vendor's list and the consents that goes with it could not be up to date if you chose to try to present before you synchronize.

Offline support

Your notice can work offline. To do so, you need to add two files locally in your application main bundle: notice.json and gvl.json.

The content of the notice and the version of the GVL must match the ones configured in the AppConsent back-office.

To get the content of your notice.json file, please contact your SFBX representative. Get the content from your SFBX representative and save it locally in your application's assets folder.

notice.json
gvl.json
notice.json

Get the content from your SFBX representative and save it locally in your application's assets folder.

notice.json
{
"buildID": number,
"noticeID": number,
"versionID": string,
"sourceID": number,
"accountID": number,
"gvlVersion": number,
"scope": string
}
gvl.json
  • Get the gvlVersion from notice.json.

  • Get the content of https://vendorlist.consensu.org/v-<gvlVersion>/vendorlist.json and save it locally in your application's assets folder.

Customizing AppConsent through the SDK

Customizing the notice behavior

You can set the behavior of the notice and geolocation notice.

Swift
Objective-C
Swift

If the notice is in single step, you can have the buttons scrolling with the purposes list.

class MyDelegate: AppConsentDelegate {
func singleStepCtaScrolling() -> Bool {
return true
}
}

For the geolocation notice, you can also decide to have the buttons scrolling with the list of geolocation purposes or enlarge the icon in the UI.

class MyDelegate: AppConsentGeolocationConsentDelegate {
func displayBigGeolocationImage() -> Bool {
return true
}
func geolocationCtaScrolling() -> Bool {
return true
}
}
Objective-C

If the notice is in single step, you can have the buttons scrolling with the purposes list.

@interface MyClass: NSObject<AppConsentDelegate>
@end
@implementation MyClass
- (BOOL)singleStepCtaScrolling {
return YES;
}
@end

For the geolocation notice, you can also decide to have the buttons scrolling with the list of geolocation purposes or enlarge the icon in the UI.

@interface MyClass: NSObject<AppConsentGeolocationConsentDelegate>
@end
@implementation MyClass
- (BOOL)displayBigGeolocationImage {
return YES;
}
- (BOOL)geolocationCtaScrolling {
return YES;
}
@end

Customizing assets

The images you can set through this API can also be customized in the back-office (for more information, read this page). If set, the images you set locally in your application will be used if there is no customization in the back-office, or as a fallback in case of network failure.

You can customize images and some texts by implementing the AppConsentAssetsProvider protocol. All properties of this protocol are optional.

@objc public protocol AppConsentAssetsProvider {
/** The icon of your application */
@objc optional var applicationIcon: UIImage? { get }
/** The image to use as a back image in navigation controller */
@objc optional var navigationBackImage: UIImage? { get }
/** The notice first screen image */
@objc optional var noticeOnboardingImage: UIImage? { get }
/** The notice success screen image */
@objc optional var noticeSuccessImage: UIImage? { get }
/** The notice information icon */
@objc optional var noticeInformationIcon: UIImage? { get }
/** The icon used for geoloc purposes */
@objc optional var geoAdvertizingIcon: UIImage? { get }
/** The title of the notice onboarding */
@objc optional var onboardingTitle: String? { get }
}

Once you've created your class implementing the protocol, return an instance in your AppConsentDelegate implementation.

Swift
Objective-C
Swift
func assetsProvider() -> AppConsentAssetsProvider {
return MyAssetsProvider()
}
Objective-C
- (id<AppConsentAssetsProvider>)assetsProvider {
return [[MyAssetsProvider alloc] init];
}

Example

In the following examples, AppConsentKit is implemented in the AppDelegate class. If the purpose is to display the notice as soon as possible in the app lifecycle, feel free to implement it where it's the best fit for you.

Swift
Swift
import AppConsentKit
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, AppConsentGeolocationConsentDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
self.window?.makeKeyAndVisible()
let url = URL(string: "https://my.notice/notice.json")
AppConsent.start(withNoticeUrl: url);
let willPresent: Bool = AppConsent.presentNotice(delegate: self, withMode: .automatic)
if !willPresent {
// try to present geo notice if standard did not appear
AppConsent.presentGeoNotice(delegate: self, withMode: .automatic)
}
return true
}
func appConsentDidFinish() {
// start advertising calls
}
func appConsentDidFail(_ error: Error) {
print("app consent did fail: \(error.localizedDescription)")
}
func appConsentCMPReady(_ cmp: AppConsentCMP) {
let viewController = UIApplication.shared.keyWindow!.rootViewController!
cmp.present(onViewController: viewController)
}
func appConsentGeoAdvertizingConsentReceived(accepted: Bool) {
// start advertising calls
}
func appConsentGeoAdvertizingConsentFailed(error: Error) {
print("geo advertizing failed \(error.localizedDescription)")
}
}

Updating SDK from 1.7 (or earlier) to 2.0.0 (or newer)

1. Create a new source with a bundle ID and a new notice

Since the version 2.0.0, you need to have a notice, specific to your Mobile App iOS, linked to a source with a bundle ID (instead of a target url).

To do so , you need to : 1) Create a new source. This source needs to have a "Mobile app" type and a bundle ID. See the section Quick Start in order to learn how to create a Source.

2) Create a new notice for your Mobile App iOS : see this section to learn how to create a notice for mobile app.

2. Update the AppConsent SDK

You can find the download link here

3. Replace the notice url with the new one

Once your new notice is created and the SDK updated, you need to replace the "resource url" with the new one in your application. Read this page to learn how to get your resource url.

4. Update your assets files for the offline notice version

For the offline version of your notice, you need to update your assets files:

  • Update the file "notice.json" :

    • Open the resource url of your notice in your browser, and copy-paste the code in your notice.json file.

    • In this notice.json file: delete all the images links (if you have some):

  • Update the images files in the builder: If your notice is customized with some images, you need to define this same visual assets in the builder for the offline version: Read this page for more information.

  • Update your GVL.json file: Make sure that your online notice and your offline notice have the same GVL number version.

    (You can find the number of the GVL, in your notice form, in the backoffice)

    If not, you need to update the GVL.json file in your assets: copy paste the information from this link : https://vendorlist.consensu.org/v-NUMBER_OF_YOUR_GVL/vendorlist.json

  • Delete this two files in your assets: Pubvendros.json and ExtravendorList.json Now, the information of this two files is in the notice.json file

XChange usage

Share user data

In your project settings, select your app target and go to Signing & Capabilities to add the Access WiFi Information capability if you don't already have it.

Then in your app code configure an instance of XChangeUserInfo and post it.

Swift
Objective-C
Swift
let userInfo = XChangeUserInfo()
userInfo.email = "[email protected]"
userInfo.phoneNumber = "0000000000"
userInfo.firstName = "Firstname"
userInfo.lastName = "Lastname"
userInfo.streetNumber = "Number"
userInfo.streetName = "Street name"
userInfo.streetType = "Street Type"
userInfo.floor = "Floor"
userInfo.town = "Town"
userInfo.region = "Region"
userInfo.postCode = "Post code"
userInfo.country = "Country"
userInfo.gender = .male
userInfo.dateOfBirth = Date()
userInfo.revenues = "Revenues"
userInfo.household = "Household"
userInfo.age = 42
userInfo.externalId = "external-id"
userInfo.csp = "CSP"
userInfo.unstructuredData = NSDictionary(dictionary: [
"Key": "Value",
"BoolKey": true
])
AppConsent.postXChangeUserInfo(userInfo) { error in
print("prime posted: \(error?.localizedDescription ?? "no error")")
}
Objective-C
XChangeUserInfo *userInfo = [[XChangeUserInfo alloc] init];
[userInfo setExternalId:@"external-id"];
[userInfo setFirstName:@"Firstname"];
[userInfo setLastName:@"Lastname"];
[userInfo setStreetNumber:@"Number"];
[userInfo setStreetName:@"Street name"];
[userInfo setStreetType:@"Street type"];
[userInfo setFloor:@"Floor"];
[userInfo setTown:@"Town"];
[userInfo setRegion:@"Region"];
[userInfo setPostCode:@"Post code"];
[userInfo setCountry:@"Country"];
[userInfo setGender:XChangeGenderMale];
[userInfo setDateOfBirth:[NSDate dateWithTimeIntervalSince1970:23456]];
[userInfo setRevenues:@"Revenues"];
[userInfo setHousehold:@"Household"];
[userInfo setAge:42];
[userInfo setCsp:@"CSP"];
[userInfo setPhoneNumber:@"0000000000"];
[userInfo setEmail:@"[email protected]"];
[userInfo setUnstructuredData:@{@"Key": @"Value"}];
[AppConsent postXChangeUserInfo:userInfo then:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"%@", error.localizedDescription);
}
}];

If you try to send user data before the user gave his consent, the callback will be called with an error.

Sharing geolocation information

Application setup

Before you can use the user's geolocation information, you will need to configure geolocation inside your app.

  • Enable Location updates and Background fetch in Background Modes

In your project settings, select your app target and then Signing and Capabilities. If you haven't enabled Background Modes yet, add it and select Location updates and Background fetch.

  • Set locations usage descriptions

In your info.plist file, add the following keys and values if you haven't already.

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Usage description</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Usage description</string>

If you support iOS 10 or lower, you may need to also add the key NSLocationAlwaysUsageDescription.

Start sharing location

Start sharing your user's location by calling the following method. You should call this method

Swift
Objective-C
Swift
let willShare: Bool = AppConsent.shareUserLocation(requestAuthorizationIfNeeded: true)
Objective-C
BOOL willShare = [AppConsent shareUserLocationWithRequestAuthorizationIfNeeded:YES];

The requestAuthorizationIfNeeded parameter controls wether or not the system authorization alert should be displayed to the user if needed. If you call this method with false while the system alert should be displayed, nothing will happen and the method will return false.

The method will also do nothing and return false if the user consents doesn't allow geolocation data sharing.

A good entry point to start sharing location would be when a notice disappear.

Swift
Objective-C
Swift
func appConsentDidDisappear() {
AppConsent.shareUserLocation(requestAuthorizationIfNeeded: true)
}
Objective-C
- (void)appConsentDidDisappear {
[AppConsent shareUserLocationWithRequestAuthorizationIfNeeded:YES];
}

If you want to share user location, don't forget to restart location sharing when your app starts.

Swift
Objective-C
Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
AppConsent.shareUserLocation(requestAuthorizationIfNeeded: false)
return true
}
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[AppConsent shareUserLocationWithRequestAuthorizationIfNeeded:NO];
}