Leveraging RampID and UID2

Overview

Publishers that collect an email address or a phone number at sign-in can convert it into a privacy-safe, encrypted identifier and pass that identifier to BidMachine. Demand partners use these identifiers to recognise authenticated users without receiving any raw personal data, which improves match rates and unlocks demand that is otherwise unavailable on unauthenticated traffic.

BidMachine SDK accepts extended IDs as external user IDs in targeting parameters and forwards them to demand partners in the bid request as user.ext.eids, together with the applicable consent signals.

Supported identifiers

Identifier	Provider	source value	What you pass
RampID	LiveRamp	liveramp.com	LiveRamp identity envelope generated by the Authenticated Traffic Solution (ATS)
UID2	Unified ID 2.0	uidapi.com	UID2 advertising token generated by the UID2 SDK

You can pass one or both identifiers on the same request.

info

BidMachine SDK does not generate identifiers itself and never receives raw emails or phone numbers. Generate the envelope or token with the identity provider's SDK or API, then hand the resulting value to BidMachine.

RampID (LiveRamp)

BidMachine collaborates with LiveRamp and uses the LiveRamp Authenticated Traffic Solution (ATS) API. For more information on ATS and how it works, refer to the LiveRamp documentation.

BidMachine accepts only the LiveRamp identity envelope. Learn more about the identity envelope here.

To participate:

1. Establish a contract and integration with LiveRamp.
2. Generate an identity envelope using ATS.
3. Pass the envelope to BidMachine SDK as an external user ID with the source liveramp.com, as shown in Passing extended IDs to BidMachine SDK.

UID2 (Unified ID 2.0)

UID2 is an open-source identity framework that converts a normalised email address or phone number into an encrypted advertising token. The token is generated on the device by the UID2 mobile SDK and refreshed automatically while the user stays signed in.

To participate:

1. Register with UID2 and obtain a subscription ID and public key from the UID2 Portal.
2. Integrate the UID2 mobile SDK and generate an advertising token from the user's email address or phone number. See Generating a UID2 token.
3. Pass the advertising token to BidMachine SDK as an external user ID with the source uidapi.com, as shown in Passing extended IDs to BidMachine SDK.

warning

Make sure your privacy policy and consent flow cover sharing a privacy-safe identifier derived from an email address or phone number with advertising partners before enabling UID2.

Generating a UID2 token

The samples below show the client-side flow described in the UID2 client-side mobile integration guide. Normalise the email address first (trim whitespace, lowercase); the UID2 SDK handles hashing.

Java

import com.uid2.UID2Manager;
import com.uid2.GenerateIdentityResult;
import com.uid2.data.IdentityRequest;
import kotlin.Unit;

// Initialize once, for example in Application.onCreate()
UID2Manager.init(this);

// Where the user signs in
UID2Manager.getInstance().generateIdentity(
        new IdentityRequest.Email("user@example.com"),
        subscriptionId,   // from the UID2 Portal
        publicKey,        // from the UID2 Portal
        result -> {
            if (result instanceof GenerateIdentityResult.Success) {
                // identity established
            } else if (result instanceof GenerateIdentityResult.Error) {
                // handle ((GenerateIdentityResult.Error) result).getEx()
            }
            return Unit.INSTANCE;
        });

// Read the current token before each ad request
String advertisingToken = UID2Manager.getInstance().getAdvertisingToken();

Kotlin

import com.uid2.UID2Manager
import com.uid2.GenerateIdentityResult
import com.uid2.data.IdentityRequest

// Initialize once, for example in Application.onCreate()
UID2Manager.init(context = this, isLoggingEnabled = true)

// Where the user signs in
UID2Manager.getInstance().generateIdentity(
    IdentityRequest.Email("user@example.com"),
    subscriptionId,   // from the UID2 Portal
    publicKey,        // from the UID2 Portal
) { result ->
    when (result) {
        is GenerateIdentityResult.Success -> { /* identity established */ }
        is GenerateIdentityResult.Error -> { /* handle result.ex */ }
    }
}

// Read the current token before each ad request
val advertisingToken = UID2Manager.getInstance().getAdvertisingToken()

Swift

import UID2

// Optional, before the first UID2Manager.shared access; defaults to production
UID2Settings.shared.uid2Environment = .production

// Where the user signs in; the SDK persists and refreshes the identity itself
if await UID2Manager.shared.identity == nil,
   let email = IdentityType.NormalizedEmail(string: "user@example.com") {
    try await UID2Manager.shared.generateIdentity(
        .email(email),
        subscriptionID: subscriptionID,   // from the UID2 Portal
        serverPublicKey: serverPublicKey  // from the UID2 Portal
    )
}

// Read the current token before each ad request
let advertisingToken = await UID2Manager.shared.getAdvertisingToken()

Passing extended IDs to BidMachine SDK

Pass each identifier as an external user ID with the matching source value. The samples below pass both a LiveRamp envelope and a UID2 token; omit the one you do not use.

Java

public TargetingParams createTargetingParams(String liveRampEnvelope, String uid2Token) {
    List<ExternalUserId> externalUserIds = new ArrayList<>();
    externalUserIds.add(new ExternalUserId("liveramp.com", liveRampEnvelope));
    externalUserIds.add(new ExternalUserId("uidapi.com", uid2Token));

    TargetingParams targetingParams = new TargetingParams();
    targetingParams.setExternalUserIds(externalUserIds);
    return targetingParams;
}

Kotlin

fun createTargetingParams(liveRampEnvelope: String, uid2Token: String): TargetingParams {
    return TargetingParams().apply {
        setExternalUserIds(
            listOf(
                ExternalUserId("liveramp.com", liveRampEnvelope),
                ExternalUserId("uidapi.com", uid2Token),
            )
        )
    }
}

Swift

import BidMachine

BidMachineSdk.shared.targetingInfo.populate {
    $0.appendExternalId("liveramp.com", liveRampEnvelope)
    $0.appendExternalId("uidapi.com", uid2Token)
}

Objective-C

#import <BidMachine/BidMachine.h>

[BidMachineSdk.shared.targetingInfo populate:^(id<BidMachineTargetingInfoBuilderProtocol> builder) {
    [builder appendExternalId:@"liveramp.com" :liveRampEnvelope];
    [builder appendExternalId:@"uidapi.com" :uid2Token];
}];

Unity

var targetingParams = new TargetingParams
{
    ExternalUserIds = new[]
    {
        new ExternalUserId { SourceId = "liveramp.com", Value = liveRampEnvelope },
        new ExternalUserId { SourceId = "uidapi.com", Value = uid2Token }
    }
};

BidMachine.SetTargetingParams(targetingParams);

On Android and Unity, TargetingParams can be set globally or on the ad request builder. See the platform pages for details: Android, Unity.

Keep the UID2 token fresh

The UID2 advertising token is short-lived and is refreshed by the UID2 SDK in the background. Read the current token and set it on each ad request or refresh cycle rather than once at initialization. A stale token will not match on the demand side.

What BidMachine sends to demand partners

BidMachine forwards the identifiers unchanged in the bid request:

{
  "user": {
    "ext": {
      "eids": [
        {
          "source": "liveramp.com",
          "uids": [
            { "id": "<LiveRamp identity envelope>" }
          ]
        },
        {
          "source": "uidapi.com",
          "uids": [
            { "id": "<UID2 advertising token>", "atype": 3 }
          ]
        }
      ]
    }
  }
}