Launch a Preference Center from a mobile app

How to launch a Preference Center from a mobile app

When launching a Preference Center from a mobile app, the user is taken from your app to the Preference Center running in WebView. While the user is authenticated in your mobile app, this authentication gets lost when the Preference Center is loaded.

To launch a Preference Center from a mobile app and pass the user authentication information, you will need to:

• Create a consent token for your Preference Center in your app backend

• Launch your preference center in a WebView

Create a consent token and an authenticated URL in your app backend

A consent token is generated by sending an API request to the Didomi API that includes the user information (in particular, the organization user ID).

To create a consent token, send an HTTP POST request to the Didomi API:

POST https://api.didomi.io/consents/tokens?organization_id=<ID of your organization>
{
    "organization_id": "<ID of your organization>",
    "organization_user_id": "<User ID>",
    "lifetime": 3600
}

Read more about authenticating with the Didomi API and creating a consent token.

As the private API key must remain private, your app must first call you app backend in an authenticated context and your app backend can then call the Didomi API:

Once you have obtained a consent token, you can generate an authenticated URL to the Preference Center by adding the consent token to the Preference Center URL in a token query-string parameter.

Example: https://privacy.company.com/?token={id_token}

We recommend that your backend returns the full authenticated URL with the token so that your app can simply launch that URL and does not hardcode any part of the URL.

Firebase

If your app is using Firebase, you can easily create an authenticated URL via a Cloud Function. We provide a Cloud Function to create a Preference Center URL that can be deployed to your Firebase account: https://github.com/didomi/firebase

The createPreferenceCenterURL Cloud Function will return the authenticated Preference Center URL with the user email from Firebase Authentication. It requires users to be authenticated via Firebase Authentication.

You then can call the Firebase function from your app with:

Android (Java)

private Task<String> getPreferenceCenterURL() {
    return mFunctions
            .getHttpsCallable("createPreferenceCenterURL")
            .call()
            .continueWith(new Continuation<HttpsCallableResult, String>() {
                @Override
                public String then(@NonNull Task<HttpsCallableResult> task) throws Exception {
                    // This continuation runs on either success or failure, but if the task
                    // has failed then getResult() will throw an Exception which will be
                    // propagated down.
                    String preferenceCenterURL = (String) task.getResult().getData();
                    return preferenceCenterURL;
                }
            });
}

Android (Kotlin)

private fun getPreferenceCenterURL(): Task<String> {
    return functions
            .getHttpsCallable("createPreferenceCenterURL")
            .call()
            .continueWith { task ->
                // This continuation runs on either success or failure, but if the task
                // has failed then result will throw an Exception which will be
                // propagated down.
                val preferenceCenterURL = task.result?.data as String
                preferenceCenterURL
            }
}

iOS (Swift)

functions.httpsCallable("createPreferenceCenterURL").call() { (result, error) in
  if let error = error as NSError? {
    if error.domain == FunctionsErrorDomain {
      let code = FunctionsErrorCode(rawValue: error.code)
      let message = error.localizedDescription
      let details = error.userInfo[FunctionsErrorDetailsKey]
    }
    // ...
  }
  if let text = (result?.data as? [String: Any])?["text"] as? String {
    self.resultField.text = text
  }
}

Launch a Preference Center

Once you have obtained an authenticated URL to the Preference Center, simply open it in a WebView or in the device browser.

Android (WebView)

import android.view.View;
import android.webkit.WebView;
import android.webkit.WebViewClient;

/**
 * Click handler to call when the user clicks on the menu item/link
 * that should open the Preference Center
 *
 * We assume that you have a WebView created with ID preferenceCenterWebView
 * and the correct Internet permissions as per https://developer.android.com/guide/webapps/webview.html
 */
public void preferenceCenterClickHandler(View view) {
    String preferenceCenterURL = ...; // Get the Preference Center URL as described above
    WebView preferenceCenterWebView = (WebView) findViewById(R.id.preferenceCenterWebView);

    // Ensure that the user stays in the WebView when he navigates
    preferenceCenterWebView.setWebViewClient(new WebViewClient());

    // Enable JavaScript
    preferenceCenterWebView.getSettings().setJavaScriptEnabled(true);

    // Load the URL
    preferenceCenterWebView.loadUrl(preferenceCenterURL);

    // TODO: Actually show the WebView here
}

Android (Browser / Intent)

import android.content.Intent;
import android.net.Uri;
import android.view.View;

/**
 * Click handler to call when the user clicks on the menu item/link
 * that should open the Preference Center
 */
public void privacyCenterClickHandler(View view) {
    String preferenceCenterURL = ...; // Get the Preference Center URL as described above
    Intent launchBrowser = new Intent(Intent.ACTION_VIEW, Uri.parse(preferenceCenterURL));
    startActivity(launchBrowser);
}