You use Ringba's custom scoring to receive information from your buyers during real-time bidding. The system sends a request to your buyer to check for agent availability and the score for the caller. You can also send and receive custom tags from Ringba so they can decide whether to bid.
Note: You must have real-time bidding enabled in your account to use custom scoring. Contact your Ringba account manager to enable it for your account.
This article contains the following sections:
Setting Up Custom Scoring
Once you have custom scoring enabled in your account, you need to configure it. To complete the configuration, you need an API endpoint from your buyer so it can be integrated into your campaign. This article explains each step:
- Obtain the buyer's API endpoint settings information
- Configure and test the buyer request (ping)
- Configure parsing steps
Note: Ringba sends all real-time bidding requests received for your campaign to the configured endpoint.
Step 1: Obtain the buyer's API endpoint settings information
Before configuring the custom scoring integration, Ringba lets you run a request to the buyer's endpoint so you can use the response to help you with the setup.
- The initial step is to contact your buyer to obtain the information you need to make a successful request to the endpoint. You need a URL which HTTP method (usually GET) to use. If using an HTTP Method other than GET, you also need a valid JSON body.
- When sending requests to buyers, it's important to be sure what type of tags they require for your request (ping). Without all the required information, you request may fail.
For example, some buyers may request that you provide the caller's ZIP Code or state or other tag to verify availability and score. However, not all buyer's require additional information, so if your buyer doesn't require any additional information, simply pinging for availability is enough.
- Headers may or may not be necessary depending on the buyer's API specifications. If headers are required, the buyer must provide you with the specific key and value information.
Step 2: Testing the endpoint
After obtaining the request settings, you can start the setup. In the Campaign > RTB tab, scroll to the Custom Scoring section. You see options for Disabled, Enabled or Required.
- Disabled: The feature is off for your campaign.
- Enabled: Ringba attempts to connect with your buyer's API endpoint. If the connection times out (limit is 2.5 seconds), the RTB bid still proceeds.
- Required: The API endpoint must return information to proceed. If the buyer's API endpoint does not return any information, Ringba generates a 3rd party enrichment code error for your publishers.
If your buyer requests tags from you, simply select the tags macros from the list by clicking the Token button on the right side of the field. This automatically populates the tag name during the bid process. During setup you are prompted to add a test value, which Ringba uses on the test request (ping) to your buyer.
For example, if the buyer requests that you send the ZIP Code, you are prompted to enter a real ZIP code value for the Sample Token Value in that specific tag token.
Once you have entered the request settings (URL, Method, Body, and Headers) and added sample token values (if applicable), you run the request to the buyer's API endpoint.
The response appears in green if the request was successful and you can view the full response. If the response fails, it appears in red, and you can view the response to understand what went wrong and update the request settings to try again.
After a successful request, you can proceed to the next step.
Note: If you make changes to the URL or score paths and want to undo them, you can easily revert back to the previous setup. The system automatically saves the previous information and all you need to do is click Revert Unsaved Changes.
Step 3: Configure parsing steps
3.1 Acceptance parsing
Acceptance parsing is required because it indicates whether you can proceed. For example, if your buyer wants you to move ahead with the bid, they may return a property named available with a value of true. To configure your acceptance parsing correctly:
- select available from the list of properties
- select Equals as the operator
- enter true as the value
As another example, the buyer might return a property named agents with a value that indicates the number of agents available. To configure your acceptance parsing, you:
- select agents as the property
- select an operator you’d like to use
- enter a value to complete the condition
In the screenshot below, the bid proceeds if the agents property is Greater Than the value 3.
The buyer might return the agents tag with a value when they return the number of agents available. You can then select the number of agents you want to consider for moving on with the bid. Using this method, you can set up agents, the operation greater than and the value 3 or any other value you desire.
3.2 Score parsing
Score parsing is not required. If your buyer wants to rate a particular caller/bid, they can provide you with a numerical score. You can utilize this score as a bid modifier or for reporting purposes. Simply indicate which property contains the score, such as score in this example.
3.3 Custom tags
Custom tags are not required. If your buyer wants to send you information back in the bid, such as a number or a message, select the corresponding tag from the options and click Add.
After completing all those section, just click Save at the end of the page and the feature is ready to use.
Custom Scoring FAQ
How can I include the RTB ID in the request?
Use the tag [tag:rtb:bidid] to include the RTB ID.
How do I use the score tag as a bid modifier?
You can use the score property as a bid modifier when you set up real-time bidding on the campaign's Real Time Bidding tab. Enter it as a tag and configure the remaining logic. In the example below, the returned score property is named Score, so you enter the bid modifier tag as Data:Score.
Tip: Once you complete the logic don’t forget to save it.
How can I check logs about custom scoring?
Once you start using the custom scoring feature, you can check a specific bid log (rejected or accepted). Navigate to Reporting > Real Time Bidding, and use the Search Bids tool to find the bid log.
The custom scoring logs appear under the Events tab on the bid log. For more information, see the Search Bids by ID article.
Can my buyer send information to my publisher on the RTB ping?
If your buyer wants to send a message back to your publisher for any rejected or accepted bid, they can include the parameter contractMessage in their response. Ringba passes this information to your publishers.
You don't need to make any changes to your setup. Just tell your buyer to include this on their API if you want the publisher to receive it.
This is an example of a successful request with the RTB contract for your publisher with a message from the buyer.
This one is an example of how it looks like for a rejected one, in case your buyer wants to send a message to your publisher.