Getting Started with Custom Bid Router

This MediaMath document describes the client integration process for the Custom Bid Router service and utilization of the API endpoints.

Custom Bid Router Activation

The Custom Bid Router feature needs to be activated on each organization before this service can be utilized.

Please contact your account representative in order to have this service activated and initiate the onboarding phase.

After an introduction to the Custom Bid Router architectural documentation and in conjunction with your Custom Bid Router onboarding team, you will be in a position to deliver the Production and Sandbox endpoint configuration details to your onboarding team. This information will then be entered into your account settings and the service ready to use.

Custom Bid Router Endpoint Configuration

Custom Bid Router endpoints need to be created for each biddable region you wish to participate in. Please provide the following details to your Custom Bid Router onboarding team for each production and sandbox endpoint.

Custom Bid Router Endpoint Regions

A ‘POP’ is the MediaMath name for each of our major server locations and are named after the major airports in those regions. It is recommended your endpoints are as close as possible to these locations to cut down on network latency and reduce the risk of timeouts.

The available POP IDs are as listed below.

Custom Bid Router Endpoint Summary

Once the service has been activated, you can verify the configuration by invoking the following API endpoint.

curl -X GET \
  https://api.byoa.mediamath.com/custombidrouter/{org_id}/configuration \
     -H 'authorization: Bearer <oauth_access_token>'

Custom Bid Router Executor

As shown in the Custom Bid Router architecture diagram, there is a logical grouping for your Custom Bid Router endpoints which are then applied to specific campaigns. This grouping when created by the Custom Bid Router onboarding team is asigned an identifier called an executor_id that will be used during Campaign configuration and rate control. A Production and Sandbox Executor will be created and can be utilized in accord with the terms of each.

Each Custom Bid Router endpoint created is specific to one or more geographies where bid requests originate.

Working with your Custom Bid Router onboarding team, you have the flexibility to customize the service and group these endpoints into one or more executors allowing customized evaluation of bid requests at the granularity you would like.

Custom Bid Router Executor Summary

Once the service has been activated, you can verify the executor_id by invoking the following configuration summary API endpoint. The executor_id returned in the response will be utilized in the campaign settings.

Receiving Bid Requests to the Custom Bid Router endpoints

The MediaMath Bidder identifies which strategies are eligible to participate in the auction for that bid opportunity. In order to be eligible, the bid must match the strategy's targeting, the strategy must be eligible to spend based on pacing and budgeting, and there must be capacity under the user's frequency cap (and budget) for that strategy, campaign, and advertiser. The bid opportunities that have been filtered to meet these criteria are forwarded to the Custom Bid Router consumer's endpoint.

Campaign Configuration Example

In the example below Custom Bid Router executor 4 is enabled for Campaign 123456. At this point MediaMath will have provisioned the executor for the Custom Bid Router consumer and all endpoints during the onboarding phase. Once the custom endpoints are configured and believed to be ready to receive traffic, campaigns must be enabled and directed to use the custom routing. If the custom routing will be used around a new campaign, this campaign must be first created in T1 in order to have access to the identifying campaign ID that will be used here. Additionally, that campaign needs to be enabled in MediaMath's bidder, by requesting a config change through your MediaMath technical contact.

During testing phase of a new campaign, typically a Sandbox executor will be configured here. A Sandbox executor does not forward the bid response from the MediaMath Custom Bid Router to MediaMath's bidders and the Campaign will not spend based on the endpoint responses. However, there are costs associated with any AWS S3 logs into your bucket and the QPS for the endpoint traffic.

curl -X PUT "https://api.byoa.mediamath.com/campaign_settings/123456" \
    -d '{
    "settings": [
        {
        "executor_id": 4,
        "high": 99,
        "low": 0,
        "namespace": "{org_id}"
        }
    ],
    "uuid_type": "UUID"
    }' \
    -H 'authorization: Bearer <oauth_access_token>'

Bid opportunity Rate Limiting

The sample rate of an endpoint can be adjusted to selectively forward only a percentage of the bid opportunities. In this example below, the sample rate was set to 75% meaning 75% of matched bid opportunities would be sent to your endpoint. The sample rate can be adjusted by the client collectively for all endpoints of an executor. This feature is useful while rolling out your deployment and for overall management of system utilization and managing endpoint and QPS costs.

curl -X PATCH \
    https://api.byoa.mediamath.com/custombidrouter/{org_id}/executors/4 \
    -d '{"sample_rate": 75,
		     "endpoint_type": "bid"}' \
    -H 'authorization: Bearer <oauth_access_token>'

T1 Permission Requirements for Custom Bid Router Endpoints

Terminology

Authentication

Login to MediaMath T1 API

Access to the Custom Bid Router API requires authorization parameters be sent as part of the API request.

The following section describes how to obtain the oauth_access_token parameter referenced in the above documentation. Please reach out to developers@mediamath.com so we can work with you to create the Client ID and Client Secret for you to access the MediaMath API.

1. Login to MediaMath T1 API

   $curl --request POST \
   --url https://auth.mediamath.com/oauth/token \
   --header 'content-type: application/json' \
   --data '{
     "grant_type":"password",
     "username":"<username>",
     "password":"<password>",
     "audience":"https://api.mediamath.com/",
     "scope":"",
     "client_id":"<client_id>",
     "client_secret":"<client_secret>"
     }'

2. Verify the response contains the access token that will be used in all future requests to the T1 API.

   {
       "access_token": "<oauth_access_token>",
       "expires_in": 86400,
       "token_type": "Bearer"
   }

3. Optionally verify the expiration date of the access token by decoding the JWT or calling the session endpoint of MediaMath T1 API

   $ curl --request GET \
     --url https://api.mediamath.com/api/v2.0/session \
     --header 'Accept:application/vnd.mediamath.v1+json' \
     --header 'Authorization:"Bearer <oauth_access_token>"'

   {
     "data" : {
         "session" : {
           "current_time" : "2001-01-01T12:00:00",
           "sessionid" : "<sessionid>",
           "expires" : "2001-01-01T13:00:00"
         },
         "entity_type" : "user",
         "name" : "email@example.com",
         "id" : 21370
     },
     "meta" : {
         "status" : "ok"
     }
   }

In order to avoid unexpected errors, please pre-validate the expiration of the token

Bid Opportunity Request Specification

Custom Bid Router will query external Executor with a Protobuf POST request that includes the OpenRTB bid request with MediaMath's extension field. We will send 1 request per auctionID.

The POST request content is an OpenRTB bid request with MediaMath extensions. The protobuf schema can be found here: https://github.com/MediaMath/bid-valuator-endpoint-java/blob/master/src/main/proto/google/openrtb/openrtb.proto

The request can have multiple bid candidates, if there are multiple strategies setup with the campaign.

We are we're sending Protobuf data by setting the Content-Type as application/protobuf.

The X-Timeout header field specifies how long the external Executor has time (in milliseconds) to reply back to MediaMath's Custom Bid Router. If the external Executor exceeds that time, we will handle the response as a timeout and not use it in scoring the bid request.