DataGrail Consent iOS SDK

Beta Feature

Mobile App Consent Management is in beta for select customers and prospects. Please contact your Account Manager or support@datagrail.io for more information.

The DataGrail Consent iOS SDK provides a fully native Swift implementation for managing user consent preferences in your iOS applications. This guide covers installation, configuration, and usage of the SDK.

Requirements

• iOS 13.0 or later
• Swift 5.7 or later
• Xcode 14 or later

Installation

The SDK can be installed using Swift Package Manager (Recommended) or CocoaPods.

Swift Package Manager

Add the DataGrail Consent SDK to your project using Swift Package Manager:

1. In Xcode, go to File → Add Packages
2. Enter the repository URL: https://github.com/datagrail/consent-ios.git
3. Select version 1.0.0 or later

Or add it directly to your Package.swift:

dependencies: [
    .package(url: "https://github.com/datagrail/consent-ios.git", from: "1.0.0")
]

CocoaPods

Add the following to your Podfile:

pod 'DataGrailConsent', '~> 1.0'

Then run:

pod install

Quick Start

Follow these steps to get the iOS SDK running in your app.

Initialize The SDK

Initialize the SDK early in your app's lifecycle, typically in AppDelegate.swift or your main app file:

import DataGrailConsent

@main
struct MyApp: App {
    init() {
        DataGrailConsent.shared.initialize(
            configUrl: URL(string: "https://api.consent.datagrail.io/config/YOUR_CONFIG_ID.json")!
        ) { result in
            switch result {
            case .success:
                print("Consent SDK initialized")
            case .failure(let error):
                print("Failed to initialize: \(error)")
            }
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Check if Consent is Needed

Before showing the consent banner, check if the user needs to provide consent:

if DataGrailConsent.shared.needsConsent() {
    // Show consent banner
}

Show the Consent Banner

Display the native consent banner to collect user preferences:

DataGrailConsent.shared.showBanner(from: viewController) { preferences in
    if let preferences = preferences {
        // User made a choice
        print("User consented to \(preferences.cookieOptions.count) categories")
    } else {
        // User dismissed without saving
    }
}

You can also specify a display style:

// Full screen style
DataGrailConsent.shared.showBanner(from: viewController, style: .fullScreen) { preferences in
    // Handle result
}

// Modal style (default)
DataGrailConsent.shared.showBanner(from: viewController, style: .modal) { preferences in
    // Handle result
}

Listen For Consent Changes

Register a callback to be notified when consent preferences change:

DataGrailConsent.shared.onConsentChanged { preferences in
    // Update your tracking configuration
    updateTrackingBasedOnConsent(preferences)
}

API Reference

The iOS SDK provides the following methods for managing consent in your application.

Initialization

func initialize(
    configUrl: URL,
    completion: @escaping (Result<Void, ConsentError>) -> Void
)

Initializes the SDK with your configuration URL. Call this once when your app starts.

Consent Status

func needsConsent() -> Bool

Returns true if the user needs to provide consent (no valid consent on file or consent has expired).

Get Current Preferences

func getPreferences() -> ConsentPreferences?

Returns the user's current consent preferences, or nil if none have been saved.

Save Preferences

func savePreferences(
    _ preferences: ConsentPreferences,
    completion: @escaping (Result<Void, ConsentError>) -> Void
)

Saves consent preferences locally and syncs with the backend.

Quick Actions

// Accept all categories
func acceptAll(completion: @escaping (Result<Void, ConsentError>) -> Void)

// Reject all non-essential categories
func rejectAll(completion: @escaping (Result<Void, ConsentError>) -> Void)

Category Checks

func isCategoryEnabled(_ categoryKey: String) -> Bool

Check if a specific consent category is enabled:

if DataGrailConsent.shared.isCategoryEnabled("category_marketing") {
    // Initialize marketing SDKs
}

if DataGrailConsent.shared.isCategoryEnabled("category_analytics") {
    // Initialize analytics
}

Show Banner UI

func showBanner(
    from presentingViewController: UIViewController,
    style: BannerDisplayStyle = .modal,
    completion: @escaping (ConsentPreferences?) -> Void
)

Display the native consent banner. The completion handler receives the saved preferences, or nil if the user dismissed without saving.

Consent Change Notifications

func onConsentChanged(_ callback: @escaping (ConsentPreferences) -> Void)

Register a callback to be notified whenever consent preferences change.

Reset

func reset()

Clears all stored consent data. Useful for testing or when a user logs out.

Integration Patterns

These patterns demonstrate common ways to integrate the SDK into your application architecture.

Delayed Tracking Initialization

Wait for consent before initializing tracking SDKs:

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    DataGrailConsent.shared.initialize(configUrl: configUrl) { result in
        if case .success = result {
            self.initializeTrackingIfAllowed()
        }
    }

    DataGrailConsent.shared.onConsentChanged { _ in
        self.initializeTrackingIfAllowed()
    }

    return true
}

func initializeTrackingIfAllowed() {
    if DataGrailConsent.shared.isCategoryEnabled("category_analytics") {
        // Initialize analytics SDK
    }

    if DataGrailConsent.shared.isCategoryEnabled("category_marketing") {
        // Initialize marketing SDK
    }
}

Consent Wall

Block app functionality until consent is provided:

struct ContentView: View {
    @State private var showConsentWall = false

    var body: some View {
        MainAppView()
            .onAppear {
                if DataGrailConsent.shared.needsConsent() {
                    showConsentWall = true
                }
            }
            .fullScreenCover(isPresented: $showConsentWall) {
                ConsentWallView {
                    showConsentWall = false
                }
            }
    }
}

Settings Screen Integration

Allow users to manage their preferences from app settings:

Button("Manage Privacy Preferences") {
    DataGrailConsent.shared.showBanner(from: self) { preferences in
        if let preferences = preferences {
            print("Preferences updated")
        }
    }
}

Accessibility

The SDK provides full VoiceOver support:

• All UI elements include accessibility labels describing their purpose
• Accessibility hints explain what happens when interacting with elements
• Toggle states are announced (e.g., "Marketing consent - Enabled")
• Navigation between consent layers is announced

Offline Support

The SDK automatically handles offline scenarios:

• Consent preferences are saved locally first
• Failed backend syncs are queued and retried automatically
• Exponential backoff retry (5 attempts, 250ms base delay)
• Manual retry available via retryPendingRequests()

Running the Demo App

A demo app is included to help you explore the SDK:

cd mobile/ios
./launch_demo.sh

Or manually:

1. Open DemoProject/Demo.xcodeproj in Xcode
2. Select a simulator
3. Press Cmd+R to build and run

Troubleshooting

Common issues and how to resolve them.

SDK Not Initializing

• Verify the config URL is valid HTTPS
• Check network permissions in Info.plist
• Review console for JSON parsing errors

Banner Not Showing

• Ensure needsConsent() returns true
• Verify showBanner is set to true in your config
• Check that you're passing a valid presenting view controller

Preferences Not Persisting

• Verify savePreferences() completion shows success
• Check backend connectivity
• Review offline queue with retryPendingRequests()

Next Steps

• Review the Configuration Guide for config.json options
• Explore common integration patterns
• Check the API Reference for all available methods