Real-time data integration: gRPC implementation

This document outlines guidelines for implementing gRPC-based real-time data integrations. All new real-time data integrations should use gRPC. While HTTP-based integrations may exist for legacy use cases, all new feature development and enhancements are designed for gRPC.

These guidelines apply whether the service is:

Hosted by the partner
Deployed in the Index Cloud

gRPC integration build guide

Download the official OpenRTB 2.6 Protocol Buffers specification.

Download the necessary build and proto files.

To generate the language-specific OpenRTB An open industry standard for communication between buyers and sellers of online advertising in real-time bidding auctions. It's published by the IAB. and gRPC bindings required by your service, from the command line:
1. Install make and the latest version of protoc.
2. From the build files that you downloaded, open the Makefile and choose the language(s) for which the Protocol Buffers object code should be generated.
3. Run:
  
  make

Classification endpoint

Endpoint Description

Endpoint	Description
Partners must expose an endpoint A URL which is configured to interact with a server in a specific way. accessible through a gRPC request following the agentic RTB Real-Time Bidding (RTB). The automated buying and selling of inventory for advertisements in real time, which is within milliseconds of an individual user loading a site. Protobuf Schema that you downloaded with your build files.	The SLA for Index to use your response in our auction processing is 5 milliseconds. All requests should be made in approximately 5 milliseconds, with no more than 5% of requests allowed to exceed the timeout value specified in the `tmax` value. If more than 5% of requests time out, traffic to your container will be automatically throttled, and Index may lower the QPS Queries Per Second (QPS). The number of bid requests a DSP processes per second. Also known as impressions per second. accordingly. Calls to this endpoint will use keep-alive connections to minimize network overhead. Note: This specification will be continually updated to support new requirements. Let us know if you have new fields that you would like Index to support.

Partners must expose an endpoint A URL which is configured to interact with a server in a specific way. accessible through a gRPC request following the agentic RTB Real-Time Bidding (RTB). The automated buying and selling of inventory for advertisements in real time, which is within milliseconds of an individual user loading a site. Protobuf Schema that you downloaded with your build files.

The SLA for Index to use your response in our auction processing is 5 milliseconds. All requests should be made in approximately 5 milliseconds, with no more than 5% of requests allowed to exceed the timeout value specified in the tmax value. If more than 5% of requests time out, traffic to your container will be automatically throttled, and Index may lower the QPS Queries Per Second (QPS). The number of bid requests a DSP processes per second. Also known as impressions per second. accordingly. Calls to this endpoint will use keep-alive connections to minimize network overhead.

Note: This specification will be continually updated to support new requirements. Let us know if you have new fields that you would like Index to support.

Response codes

Standard gRPC status codes should be returned.

Circuit breaker logic

If Index receives any status code other than OK, or more than 5% of requests have exceeded a timeout value of 5ms, Index's internal circuit breaker logic is triggered, and requests to the affected partner's API are throttled. Requests to a partner's API that time out will also trigger this same circuit breaker logic. Circuit breaker logic exists to protect both Index and our partners' systems. When errors rates return to nominal levels, circuit breakers will reopen and regular traffic volume will resume.

gPRC-supported lifecycle extension points and mutations

OpenRTB lifecycle extension point	Mutations	Supported paths	Use case
Slot request An ad request for a potential impression.	ACTIVATE_SEGMENTS	/user/data	Activate a list of segment IDs for a given request.
	ACTIVATE_DEALS	/imp/<impID>	Activate a list of deal A private auction that allows publishers to offer specific inventory directly to selected buyers identified by a deal ID. Terms are negotiated and are agreed upon before the auction occurs. IDs for a given request for a given imp ID. Each mutation should contain only one deal ID. Multiple deal IDs require separate mutations.
	SUPPRESS_DEALS	/imp/<impID>	Suppress a list of deal IDs for a given request for a given imp ID. Each mutation should contain only one deal ID. Multiple deal IDs require separate mutations.
	ADJUST_DEAL_FLOOR A pricing control used by publishers and exchanges to set a minimum sale price on inventory.	/imp/<impid>/deal/<dealid>	Adjust the bid floor of a specific deal.
	ADD_CONTENT_DATA (coming soon)	/content/data	Add a list of content data to site or app content object.
DSP Demand-Side Platform (DSP). A software platform that automates bidding decisions in real-time and efficiently connects buyers and audiences through an ad exchange or SSP. Also known as a buy-side platform. bid response An OpenRTB response that is sent by the DSP in response to the SSP's or ad exchange's bid request. It is an event directed back to the seller expressing a valuation for the request and conditions of sale.	BID_SHADE	/seatbid/<seatID>/bid/<bidID>	Modify a DSP bid price.