Consentric API

Integrate with IOS

Universal Consent & Preference Management... Made simple.

Integration using a WebView

The easiest integration of Consentric into an iOS app is achieved when loading our widget into a WKWebView.

Prior to doing this you will need a template set up, with a templateId, and a process that uses the Consentric API to generate a user access token. The templateId and the access token will be required for further steps.

Including the widget in a WKWebView

The Web Content to Display

First, we need to add the content that the WKWebView is going to render. To do this, add a file named index.html to your xcode project root. The contents of this file should be as follows:

<head>
    <meta name="viewport" content="width=device-width">
</head>
<body>
    <div id="widget-container"></div>
    <script src="https://scripts.consentric.io/progressive-consent.min.js"></script>
    <script>
        window.addEventListener("load", () => {
                    window
            .webkit
            .messageHandlers
            .loadedMessageHandler
            .postMessage(["Loaded", "true"  ])
        });
        const init = ({ templateId, token }) => {
            ProgressiveWidget.load({
                id: 'widget-container',
                templateId,
                token,
                events: {
                    onSuccess: (response, submission) => {
                        response.json().then((json) => {
                            window
                              .webkit
                              .messageHandlers
                              .widgetMessageHandler
                              .postMessage(["Success", JSON.stringify(json)])
                        })
                    },
                    onFailure: (error, request) => {
                        window
                          .webkit
                          .messageHandlers
                          .widgetMessageHandler
                          .postMessage(
                            [
                              "Failure",
                              JSON.stringify(({request, error}))
                            ])
                    },
                },
                consentricLogo: false,
            });
        }
    </script>
    <style>
        .mld-pc-minimise, .mld-pc-button--cancel {
            display: none;
        }
        .mld-pc-app-show {
            position: relative;
            border: none;
            box-shadow: none;
            max-height: 100%;
            min-height: 100%;
            padding: 0;
        }
        .mld-pc-app__header {
            padding: 0;
        }
    </style>
</body>
 

The snippet above may be customised, for example, to edit the CSS styles to better fit the look and feel of the surrounding app.

Setting up a ViewController

Next, this will need to be loaded into the WKWebView. You can implement a WKWebView in the way that best fits your app architecture. As an example, we have chosen a fairly standard ViewController to represent programmatically rendering the widget. This could then be pushed and popped by a NavigationController.

Our Example ViewController looks like this:

 

import UIKit
import WebKit

class ConsentricViewController: UIViewController, WKUIDelegate {
    
    var webView: WKWebView!
    
    override func loadView() {
        let widgetMessageHandler = WidgetMessageHandler()
        let webConfiguration = WKWebViewConfiguration()
        webConfiguration
            .preferences
            .javaScriptEnabled = true
        webConfiguration
            .userContentController
            .add(widgetMessageHandler, name: "widgetMessageHandler")
        webConfiguration
            .userContentController
            .add(self, name: "loadedMessageHandler")
        webView = WKWebView(frame: .zero, configuration: webConfiguration)
        webView.uiDelegate = self
        view = webView
    }
    
    override func viewDidLoad() {
        super.viewDidLoad()
        let htmlFile = Bundle.main.path(forResource: "index", ofType: "html")
        let html = try? String(
            contentsOfFile: htmlFile!,
            encoding: String.Encoding.utf8
            )
        webView.loadHTMLString(html!, baseURL: nil)
    }
    
    func handleInit(result: Any?, error: Error?) {
        print(result)
        print(error)
    }
    
    func initWidget(templateId: String, token: String) {
        webView
            .evaluateJavaScript(
                """
                    init({
                        templateId:'\(templateId)',
                        token:'\(token)'
                    });
                """,
                completionHandler: handleInit(result:error:))
    }
}

extension ManagePreferencesViewController: WKScriptMessageHandler {
       func userContentController(
          _ userContentController: WKUserContentController,
          didReceive message: WKScriptMessage
        ) {
            //Get variables for widget here
           if (message.name == "loadedMessageHandler") {
               initWidget(
                 templateId: "{{INSERT TEMPLATE ID HERE}}", 
                 token: "{{INSERT ACCESS TOKEN HERE}}"
               )
           }
       }
} 

This is a simple ViewController class that instantiates a WKWebView and uses the `index.html` file that was created earlier as the content to be rendered. On top of this, it extends the WKScriptMessageHandler class, allowing a message to be posted back when the DOM in the WKWebView has loaded.

This allows the initialisation of the widget code with the correct templateId and user access token as mentioned above. How these variables are injected here are left open for interpretation. Dependency Injection, being passed through by the NavigationController into a constructor of the ViewController, API calls, and so on may all be valid methods to obtain the values required at this point.

Capturing and using the data from the Widget

We’ve seen above an extension of the ViewController class lets us know when the page has loaded and we can render the widget. Depending on your specific implementation you may want to handle the success or failure of submitting the Widget and the resultant state. The Widget provides two callback functions which can be hooked into for a success case or a failure case. The snippet below shows an example of a separate class set up to listen to both kinds of message when using the index.html file structure provided.

 
import WebKit
import Foundation
class WidgetMessageHandler: NSObject, WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        if (message.name == "widgetMessageHandler") {
            let json = message.body as! [String]
            switch (json[0]) {
                case "Success":
                    //Handle success
                    break;
                case "Failure":
                    //Handle failure
                    break;
                default:
                    //Throw error
                print("Parse Error")
                    break;
            }
        }
    }
} 

The message structure follows a convention of an array of strings containing two elements. The first is a message indicating the outcome of the action and the second is metadata surrounding that action. As shown in the class above our messages will either have a “Success” or a “Failure” indicator. The content of the second element will vary depending on the templates used but will take the general form of stringified JSON. An example of this is shown below.

{
  "preferences": 0,
  "permissions": [
    {
      "id": "9VrZeEV93aR_bM2Bvzrfm3b",
      "applicationId": "4wcBMyS6c8Y",
      "citizenId": "PkqTeBUyCJH",
      "externalRef": "cia",
      "changes": [
        {
          "optionType": "option",
          "optionId": "3mgii2",
          "justification": "consent",
          "state": "DENIED",
          "permissionStatementId": "sjLfySwEAAP",
          "obtainedAt": "2020-04-24T15:26:11.289Z",
          "validFrom": "2020-04-24T15:26:11.289Z"
        },
        {
          "optionType": "option",
          "optionId": "DeLij3",
          "justification": "consent",
          "state": "DENIED",
          "permissionStatementId": "sjLfySwEAAP",
          "obtainedAt": "2020-04-24T15:26:11.289Z",
          "validFrom": "2020-04-24T15:26:11.289Z"
        },
        {
          "optionType": "option",
          "optionId": "FJjyD7",
          "justification": "consent",
          "state": "DENIED",
          "permissionStatementId": "sjLfySwEAAP",
          "obtainedAt": "2020-04-24T15:26:11.289Z",
          "validFrom": "2020-04-24T15:26:11.289Z"
        },
        {
          "optionType": "option",
          "optionId": "tM4zd4",
          "justification": "consent",
          "state": "GRANTED",
          "permissionStatementId": "sjLfySwEAAP",
          "obtainedAt": "2020-04-24T15:26:11.289Z",
          "validFrom": "2020-04-24T15:26:11.289Z",
          "validUntil": "2021-04-24T15:26:11.289Z"
        }
      ],
      "channel": "progressive",
      "privacyPolicyId": "uN2mttuNqDS",
      "privacyPolicyRef": "policyRef-01",
      "recordedAt": "2020-04-24T15:26:11.289Z",
      "recordedBy": "consentric|PkqTeBUyCJH",
      "recordedByName": "cia",
      "recordedBySpecifiedByClient": false,
      "recordedClient": "Authorisation Service",
      "recordedClientName": "Access Token",
      "revertable": true,
      "obtainedAt": "2020-04-24T15:26:11.289Z"
    }
  ]
}