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.

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:

1. Obtain the buyer's API endpoint settings information
2. Configure and test the buyer request (ping)
3. Configure parsing steps

Note: All Real-Time Bidding requests received for your campaign will be sent 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 obtain information from the buyer to make a successful request to the endpoint. A URL and HTTP Method (GET) are required. If using an HTTP Method other than GET, a valid JSON body is required.
• When communicating with buyers, it's important to clarify what type of tags they require for your request (ping). For example, some buyers may request that you provide the caller's ZIP code or state or any other tag to verify availability and score. However, this is not always necessary, 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), we will still proceed with the RTB bid.
• 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 will be prompted to add a test value, which will be used on the test request (ping) to your buyer.

For example, if the buyer requests that you send the ZIP code, you will be 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 will run the request to the buyer's API endpoint.

The response will be green if the request was successful and you will be able to view the full response. Alternatively, the response will be red if it fails and you will be able to 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

The acceptance parsing is required, it tells us if we can or cannot 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, you would select the property “available” from the options, the operator “Equals” from the options, and enter a value of “true”.

As another example, the buyer may return a property named "agents" and a value of the number of agents available. To configure your acceptance parsing, you would select the property “agents” from the options, an operator you’d like to use, and a value to complete the condition. In the screenshot below, the bid will proceed if the “agents” available is greater than 3.

The buyer may return the "agents" tag with a value when they return the number of agents available. You can then select the number of agents that 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

The 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 will be used to transmit 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".

The custom scoring feature will be ready upon successful completion of the configuration and save.

After choosing all, you just need to click on "Save" at the end of the page and the feature is ready to be used.

Custom Scoring FAQs, Resources, and Troubleshooting

How do I use the score tag as a bid modifier?

If you want to use the score property as a bid modifier, enter it as a tag value and configure the remaining logic. In the example below, the returned score property is named "Score", thus the bid modifier tag value is entered as “Data:Score”. 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 and want to check a specific bid log (rejected or accepted), use the search bid tab to see the bid log. The custom scoring logs will appear under the “Events” tab on the big log. If you want to know more information, please check this link Search Bids by ID.

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, the only thing that they need to do is to include the parameter "contractMessage" in their response and Ringba will pass this information to your publishers. You don't need to make any changes on 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.