Skip to main content

EUID Client-Server Integration Guide for Mobile

This guide is for mobile app publishers who want to integrate with EUID by generating EUID tokens server-side via a Public Operator or Private Operator and then passing the tokens and user identities into their mobile apps, which will in turn pass the tokens for bidstream use.  

This is called client-server integration because some integration steps are client-side and some are server-side.

If you want to integrate with EUID via client-side only changes (that is, all integration changes required are within the mobile apps), refer to the EUID Client-Side Integration Guide for Mobile instead.

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:

  • Takes in 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.

You'll need to complete the following steps:

  1. Complete the EUID account setup.
  2. Implement server-side token generation.
  3. Add the EUID mobile SDK to your mobile app.
  4. Configure the EUID mobile SDK.
  5. Check that the token was successfully generated and then pass it for bidstream use.
  6. 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.

Complete the EUID Account Setup​

To set up your account, follow the steps described in Account Setup.

When account setup is complete, you'll receive your unique API key and client secret. These values are unique to you, and it's important to keep them secure. For details, see API Key and Client Secret.

Client-Server Mobile Integration Data Flow Overview​

The following diagram shows the data flow that the publisher must implement for EUID client-server mobile integration.

This example uses the SDK for Android in the client-side mobile app and the SDK for Java on the server side.

Mobile Client-Server Integration Example

Implement Server-Side Token Generation​

For a client-server EUID integration for mobile, the first step is to be able to generate the EUID token on your server. Then, you can pass the token into your mobile apps for sending to the RTB bidstream.

For details, including instructions and examples, see Server-Side Token Generation.

You will need to pass the Identity response into the mobile app: see Configure the EUID Mobile SDK.

warning

For security reasons, the API key and secret used in token generation must be called server-side. Do not store these values inside a mobile app.

Server-Side Token Refresh​

Token refresh is automatically enabled inside the EUID mobile SDKs; you don't need to manage it explicitly on the server side.

You might decide to do server-side token refresh if you want to keep your changes in the mobile apps as simple as possible.

If you want to manage token refresh on the server side and not the client/mobile side, you can do so using one of the following:

Then, pass the newly refreshed Identity value to the mobile app by following the rest of this guide.

Add the EUID Mobile SDK to Your Mobile App​

For installation instructions, refer to one of the following:

At this point, you are ready to use the EUID Identity generated server-side in the mobile 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 EUID integration environment instead, provide the following URL in your call to EUIDManager initialization:

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 API key and client secret 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 change it in the init call:

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

Configure the EUID Mobile SDK​

After you've instantiated EUIDManager correctly in your mobile app, you'll need to pass an EUID identity generated server-side (see Implement server-side token generation), and then pass it into the mobile app using the setIdentity method, as shown in the following:

EUIDManager.getInstance().setIdentity()

Token Storage​

After you call the setIdentity method, the EUID identity is persisted in local file storage.

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​

To retrieve the token, in your mobile app, call the following:

EUIDManager.getInstance().getAdvertisingToken()

If a successful identity was added into the EUIDManager, this method returns a string such as the following:

A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

You can use this identity 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 setIdentity() 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
  • 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, follow the instructions in Implement Server-Side Token Generation again, generate a new identity, and pass the result into your mobile app's EUIDManager again.

When to Pass a new EUID Identity/Token into the SDK​

The best way to determine whether a new EUID identity is required by the EUID SDK again is to call the getAdvertisingToken() method in all cases:

EUIDManager.getInstance().getAdvertisingToken()

On startup/resumption of the app, if getAdvertisingToken() returns null, it is time to generate new identity on the server by following the instructions in Implement Server-Side Token Generation. Then, pass the result into the mobile app’s EUIDManager again: 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
)

Enable Automatic Token Refresh in Mobile App/Client Side​

By default, after a valid EUID identity has been passed into the EUIDManager, it performs automatic token refresh. If for any reason token refresh was disabled, you can enable it with the following method call:

Android Java:

EUIDManager.getInstance().setAutomaticRefreshEnabled(false)

Android Kotlin:

EUIDManager.getInstance().automaticRefreshEnabled = false

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 Integration with Prebid Mobile SDK​

important

The EUID integration with Prebid Mobile SDK 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.