Skip to main content

EUID Client-Side Integration Guide for Mobile

This guide is for mobile app publishers who want to integrate with EUID with changes only within their mobile app.

These instructions do not apply to publishers who want to use a Private Operator, or who want to generate tokens server-side. Those publishers should follow the Client-Server Integration Guide for Mobile.

This page provides a high-level overview of integration steps and links to additional documentation.

EUID provides mobile SDKs for Android and iOS. Each SDK has the following features:

  • Generates an EUID identity (an EUID token and associated values) and persists it in local file storage.
  • Automatically refreshes EUID tokens.
note

This guide uses the group term EUID mobile SDKs to include both the SDK for Android and the SDK for iOS.

For FAQs relating to mobile publisher integrations, see FAQs for Mobile Integrations.

To integrate with UIEUIDD2 client-side, you'll need to complete the following steps:

  1. Complete the EUID account setup.

  2. Add the EUID mobile SDK to your mobile app.

  3. Configure the EUID mobile SDK.

  4. Check that the token was successfully generated and then pass it for bidstream use.

  5. Optionally, integrate the EUID GMA/IMA Plugin for GAM Secure Signals integration.

Mobile SDK Version​

This guide provides instructions for using either of these EUID mobile SDKs:

  • SDK for Android (version 1.6.0 or later)
  • SDK for iOS (version 1.7 0 or later)

For instructions for installing the correct SDK/version into your mobile app, see Add the EUID Mobile SDK to Your Mobile App.

Client-Side Integration Example​

For an example of how to configure an EUID mobile SDK, and how to generate tokens using client-side integration for mobile, you can try out the EUID development app.

Follow the applicable instructions, for Android or iOS:

  1. Check out the main branch of the SDK for Android source code repository on GitHub.
  2. In Android Studio (check the version required in the Minimum Requirements section in the SDK for Android Reference Guide), open the directory that you checked out.
  3. set uid2_environment_euid to true in AndroidManifest.xml
  4. Run the dev-app app.
  5. When you've started the app, make sure that the Client Side checkbox is checked.
  6. Enter an email address, and then click the arrow to the right.

Behind the scenes, the development app makes the following EUID SDK API call. This call sends a request to the EUID service to generate an identity (an EUID token and associated values) for the email input:

EUIDManager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

When the API call is successful, the app displays the resulting identity and persists it inside the EUIDManager class.

The identity includes the generated EUID advertising token value, which you can retrieve using the getAdvertisingToken() method call:

EUIDManager.getInstance().getAdvertisingToken()

This method call returns the value that you need to make an ad request: see Pass Generated Token for Bidstream Use.

Testing With Your Own Configuration​

By default, the development app uses default values for Subscription ID and public key, which are stored in the following object:

com.uid2.dev.ui.MainScreenViewModel.Companion

By default, the development app is configured to connect to the EUID integration environment, as specified in the following Android method call/iOS file:

com.uid2.EUIDManager.Companion#init

If necessary, you can also change the default Subscription ID and public key to values assigned to you, and connect to the EUID Production environment. For details, see Optional: Specifying the API Base URL to Reduce Latency.

Complete the EUID Account Setup​

To set up your account, follow the steps described in Account Setup. As part of the account setup process, you'll need to provide a list of app names for all the mobile apps that you'll be integrating with the EUID mobile SDKs, including any of these values that apply:

  • Android Application ID
  • iOS Bundle Identifier
  • iOS App Store ID

When account setup is complete, you'll receive a client keypair consisting of two values that identify you to the EUID servers: Subscription ID and public key. These values are unique to you, and you'll use them when you configure the EUID mobile SDK. For details, see Subscription ID and Public Key.

Add the EUID Mobile SDK to Your Mobile App​

To add the mobile SDK to your app, follow the applicable documentation:

At this point, you are ready to start generating EUID tokens using the SDK.

Using the EUID Integration Environment​

By default, the SDK is configured to work with the EUID production environment: https://prod.euid.eu/v2. If you want to use the integration environment instead, provide the following URL in your call to initialize EUIDManager:

EUIDManager.init(
  context = this,
  EUIDManager.Environment.Custom("https://integ.euid.eu/v2"),
)
note

Bear in mind the following differences between environments:

  • Tokens from the EUID integration environment are not valid for passing to the bidstream.
  • You'll have a different set of Subscription ID and public key values for each environment (integration and production). Be sure to use the correct values for each environment.

Optional: Specifying the API Base URL to Reduce Latency​

By default, this SDK makes calls to an EUID production environment server in the USA.

For information about how to choose the best URL for your use case, and a full list of valid base URLs, see Environments.

To specify an EUID server that is not the default, you can make config changes, as shown in the following examples:

EUIDManager.init(
  context = this,
  EUIDManager.Environment.Custom("https://prod.euid.eu/v2")
)

Configure the EUID Mobile SDK​

EUID provides the publisher with the following values, which are needed for generating the EUID token on the client side:

  • Subscription ID
  • Public key

You'll have one set of these values for your Integration environment, and a separate set for your production environment.

To configure the SDK, you must pass in the Subscription ID and public key that you received during account setup, as well as the user’s hashed or unhashed directly identifying information (personal data) (email address), into the following method call:

EUIDManager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

Once it's configured, the EUID mobile SDK does the following:

  • Generates an EUID identity, including token, for the user.
  • Stores the token locally on the user’s device.
  • Automatically refreshes the token as required while your app is open.
tip

You can pass the user’s personal data to the EUID mobile SDK either hashed or unhashed. If you pass the personal data unhashed, the SDK hashes it for you. If you want to pass the personal data to the SDK already hashed, you must normalize it before hashing. For details, see Normalization and Encoding.

Format Examples for Personal Data​

The SDK encrypts the hashed personal data before sending it to the EUID service.

You can invoke the generateIdentity method using one of the two accepted formats for personal data, for any specific user. The personal data format might vary per user, but you can only send one value per user.

The following examples demonstrate the different ways that you can configure the EUID mobile SDK and list the requirements for the personal data passed into the SDK:

  • Email, Unhashed
  • Email, Normalized and Hashed

If the generateIdentity method is called multiple times, the EUID mobile SDK uses the most recent configuration values.

The following example configures the EUID mobile SDK with an email address.

EUIDManager.getInstance().generateIdentity(
    IdentityRequest.Email("test@example.com"),
    subscriptionId,
    publicKey,
) { result ->
    when (result) {
        is Error -> ...
        is Success -> ...
    }
}

In this scenario:

  • No normalization or hashing is required by the publisher.
  • The EUID mobile SDK normalizes and hashes the email address before sending the encrypted hash to the EUID service.

Token Storage and Refresh​

After a call to the applicable method listed in Format Examples for Personal Data is successful, an identity is generated and stored in local file storage. The EUID mobile SDK refreshes the EUID token periodically.

warning

The format of the file stored in the local file storage, or the filename itself, could change without notice. We recommend that you do not read or update the file directly.

Pass Generated Token for Bidstream Use​

In your mobile app, if the call to generateIdentity was successful, it returned an identity. The next step is to call the getAdvertisingToken() method, as follows:

EUIDManager.getInstance().getAdvertisingToken()

If successful, this method call returns the token—a non-null string object such as the following:

A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

You can use this token to pass downstream for sending in the RTB bidstream.

If the getAdvertisingToken() method call returns null, there was no identity or valid token generated.

Some possible reasons for this, and some things you could do to troubleshoot, are as follows:

  • The identity is invalid. In this scenario there are a couple of options:

    • Check to see whether there are any errors from the previous generateIdentity call.

    • Check the status of the identity, using one of the following:

      • Android Java: EUIDManager.getInstance().getCurrentIdentityStatus()
      • Android Kotlin: EUIDManager.getInstance().currentIdentityStatus()
      • iOS: EUIDManager.shared.identityStatus

      It's possible that the personal data has been opted out of EUID: for details, see When to Pass Personal Data into the SDK.

  • You could enable logging to get more information: see Enable Logging.
  • The advertising token inside the EUID identity has expired, and the refresh token has also expired, so the SDK cannot refresh the token.

If there is no identity, you'll need to call the generateIdentity method again: see Configure the EUID Mobile SDK.

For more information, see When to Pass Personal Data into the SDK (next section).

When to Pass Personal Data into the SDK​

The first time a new user opens the app, no EUID identity exists. You'll need to call the generateIdentity method, with the personal data, to start the token generation:

EUIDManager.getInstance().generateIdentity(
    identityRequest: IdentityRequest,
    subscriptionId: String,
    publicKey: String,
    onResult: (GenerateIdentityResult) -> Unit
)

When this method call completes successfully, the advertising token (EUID token) is available for you to send to the bidstream.

If the EUID identity stored in local file storage has expired and cannot be refreshed, you must call the generateIdentity method again to generate a new identity and get the resulting EUID token. The only exception is when the response to the following Android method/iOS object indicates that the personal data was opted out of EUID:

Android Java:

EUIDManager.getInstance().getCurrentIdentityStatus()

Android Kotlin:

EUIDManager.getInstance().currentIdentityStatus()

A response status of OPT_OUT for Android, or optOut for iOS, indicates that the personal data has been opted out of EUID and no identity/token should be generated for it. You might want to avoid making repeated generateIdentity calls: if the personal data has a status of opted out, the EUID token is not generated.

The best way to determine if personal data is required by the EUID mobile SDKs is to always call the getAdvertisingToken() method when the app starts up or resumes:

EUIDManager.getInstance().getAdvertisingToken()

If getAdvertisingToken() returns null, and the identity status is not OPT_OUT/optOut, you'll need to generate a new token. To do this, pass the personal data into the generateIdentity method again. For details, see Configure the EUID mobile SDK.

Enable Logging​

The EUID SDK can generate logs, which could help in debugging any issues during EUID integration work. To enable logging, do the following:

// During EUIDManager initialization:
EUIDManager.init(
  context = this,
  isLoggingEnabled = true
)

Optional: EUID GMA/IMA Plugin for GAM Secure Signals integration​

If you intend to generate EUID tokens to send to the Google GMA SDK or the Google IMA SDK, assuming you have followed the instructions in this guide, you must also add the EUID GMA/IMA plugins into your mobile app. For instructions, refer to the applicable plug-in guide:

You do not need to explicitly make the getAdvertisingToken() method call to retrieve the advertising tokens and pass them into Google GMA/IMA SDK manually. The EUID GMA/IMA plugins manage this for you.

All you need to do is make sure that getAdvertisingToken() returns a non-null string object:

EUIDManager.getInstance().getAdvertisingToken()

If the token exists, the Google GMA/IMA plug-ins can retrieve it automatically via the EUID GMA/IMA plugins.

Optional: EUID Prebid Mobile SDK Integration​

important

The EUID Prebid Mobile SDK integration requires version 1.6.0 or later of the EUID SDK for Android, or version 1.7.0 or later of the EUID SDK for iOS.

This section is for participants who want to integrate with EUID and use the Prebid Mobile SDK for header bidding in Android and iOS applications.

The EUID Prebid integration monitors the state of the UID2Identity. Whenever the state changes, the Prebid integration automatically updates Prebid’s external user IDs. This includes when an identity is refreshed, resulting in a new advertising token.

Prebid then sends the EUID tokens into the RTB bidstream, along with other external user IDs that you might set.

note

This integration requires a Prebid Server setup.

To configure your EUID Prebid for Mobile integration, follow these steps:

  1. Set up Prebid's Mobile SDK, following the steps in Prebid SDK Integration for Android or Prebid SDK Integration for iOS.

  2. Add the EUID Mobile SDK to your app, following the steps in Add the EUID Mobile SDK to Your Mobile App.

  3. The EUID Prebid integration is distributed as a separate module, so you must add it as a dependency in your project. Follow the installation instructions that apply to your integration, out of the following options:

    Include the following in your Gradle configuration:

    implementation("com.uid2:uid2-android-sdk-prebid:1.6.0")

  4. After adding the dependency, you'll need to configure the integration. First initialize the EUIDManager, and then Prebid, as shown in the following examples.

    EUIDManager.init(context = this)

    PrebidMobile.initializeSdk(this) { Log.i(TAG, "Prebid: $it") }
    prebid = UID2Prebid(EUIDManager.getInstance()).apply {
        initialize()
    }

  5. Configure a callback that's passed in during initialization.

    The EUID Prebid integration periodically updates Prebid by setting the relevant external IDs when a new identity is generated or an existing token is refreshed.

    This process is destructive, which means that if your application uses external IDs from another source, you'll need to provide those to the EUID Prebid integration so that all external IDs are retained while the EUID token is updated.

    This is done via the callback, which must be passed in during initialization, as shown in the following examples.

    prebid = UID2Prebid(
        manager = EUIDManager.getInstance(),
        externalUserIdFactory = ::getExternalIds,
    ).apply {
        initialize()
    }

Error Response States​

In certain conditions, the mobile SDK might return one of the following error response states:

note

The response states are the same for both Android and iOS.

Response State of Expired​

A response state of Expired means that the EUID token has expired but the refresh token has not expired, therefore the EUID token can be refreshed.

Automatic refresh: If you have automatic refreshing enabled on the SDK (automaticRefreshEnabled property), which is the default setting, the SDK refreshes the token for you. However, there are some scenarios where you might observe this state.

For example, if the app is launched and the SDK is immediately queried, you might see a response state of Expired while, in the background, the SDK is in the process of refreshing the token and will quickly update with the new identity.

In this scenario, no action is needed. As soon as the SDK is initialized, it will refresh the token.

Manual refresh: If you've disabled automatic refreshing of the token, and get a response state of Expired, you can manually request the refresh by calling the refreshIdentity() method.

Response State of RefreshExpired​

A response state of RefreshExpired means that the EUID token and the refresh token have both expired, therefore the EUID token cannot be refreshed.

An example of how this could occur is if a user does not run your app for a long time, and the SDK therefore doesn't get an opportunity to refresh the EUID token before the refresh token expires.

In this scenario, you'd need to regenerate the identity.

Response State of Invalid​

A response state of Invalid means that the identity, whether loaded off disk or requested via the API, did not include all the necessary tokens. This should never happen, but might occur in unexpected circumstances.

If the SDK detects this error, it clears any previous identity since it's considered unusable.

In this scenario, you'd need to regenerate the identity. Ideally, also report the issue to your EUID contact.

Response State of NoIdentity​

A response state of NoIdentity means that the SDK has been initialized, but doesn't yet have a current identity.

This happens the first time the SDK is used on a device, before any identity has been generated. In this scenario, you'd need to generate the identity.