Manage Placements

Create New Placement ๐Ÿ”—

  1. Navigate to Mediation > Placements. You will be redirected to the Helium dashboard.
  2. Select an app on the top right dropdown. Then click New Placement +. If an app is not selected, you will be prompted to import an app.
  3. Select an Ad Format.
  4. Select a a pre-defined Ad Placement Name or create your own custom name.
    • Custom name has a maximum of 50 characters and only numbers, letters, and hyphens are allowed.
    • The Ad Placement Name will be used in the Mediation SDK integration.
  5. Set the Creative Types setting.

Advanced Settings ๐Ÿ”—

Creative Types ๐Ÿ”—

All creative types are allowed by default. Allowing all creative types will help maximize your earnings. See Ad Formats for more information on creative type to ad type compatilibities.

A/B Test ๐Ÿ”—

Enabling A/B test for this placement to experiment and determine what settings is most effective.

Best practice is to not enable A/B test until you finish setting up both Bidding and/or Waterfall within the placement.

Ad Queueing ๐Ÿ”—

Ad queueing allows queueing up multiple fullscreen ads to show in succession. This can reduce and potentially eliminate latency for ad experiences that require showing fullscreen ads back to back.

This feature requires Mediation SDK 4.9.0+. Banners and adaptive banners cannot be queued.

The queue size can be set to hold 1-5 ads. This limit can be set at 3 levels on the Mediation dashboard: (1) max queue size, (2) default queue size, and (3) placement queue size.

  • Set the Queue Size for the placement. If no queue size is set here, then the Default Queue Size set on the appโ€™s detail page will apply. The Max Queue Size will take precedence if the default queue size is greater than the max queue size.
  • On the appโ€™s details page, set the Max Queue Size that applies to all of the appโ€™s placements. This setting defaults to 2. Default queue size will take precedence if it is less than the max queue size.
  • On the appโ€™s details page, set the Default Queue Size for any placements that do not have a queue size set. This setting defaults to 2. Max queue size takes precedence if it is less than the default queue size or placement queue size.

For example, if Max Queue Size is set to 4 and Default Queue Size is set to 2, then any placementโ€™s Queue Size will default to 2 if no size is set, or will have a max size of 4 if the size set is greater than 4.

If the settings are set to the following: Then the placement sizes will be:
  • Placement A: Queue Size set to 5
  • Placement B: No Queue Size set
  • Placement C: Queue Size set to 3
  • Default Queue Size: 2
  • Max Queue Size: 4
  • Placement A: 4
  • Placement B: 2
  • Placement C: 3

Rewarded Callbacks ๐Ÿ”—

When creating or editing a Rewarded placement, you will see a new toggle for configuring a rewarded callback under Advanced Settings. Click the toggle to enable rewarded callbacks on your placement.

Here you will be able to configure the following options:

Option Definition
Method The HTTP method to make the callback request with. Both GET and POST are supported
Max Retries The number of times Mediation will retry the callback if your server does not respond with a 200 OK. min=0, max=10
URL The URL to make the callback request to. Must be <https://>
Body Optional field that is only available when the method is POST. Supports the same macros as URL

Supported Macros ๐Ÿ”—

The following macros can be appended to the URL or the Body when using the POST method.

Macro Definition Required?
%%TRANSACTION_ID%% A unique impression ID associated with the rewarded event Required
%%SERVER_TIMESTAMP%% A UNIX timestamp set by the Mediation server when the event is processed Required
%%USER_ID%% A publisher specific user ID associated Required
%%VERIFICATION%% A SHA256 hash encrypted with your rewarded secret key by the Mediation server Required
%%SDK_TIMESTAMP%% A UNIX timestamp set by the Mediation SDK when the event is processed Optional
%%CPM_PRICE%% The CPM price of the ad unit that was served Optional
%%AD_REVENUE%% The actual ad revenue value from the impression. CPM_PRICE / 1000 Optional
%%CUSTOM_DATA%% A key value JSON payload provided via the SDK that contains custom data Optional

Make sure all the required macros are present otherwise you will not be able to save the callback.

An example of a URL containing all the required macros:

Creating a Rewarded Secret Key ๐Ÿ”—

To create or obtain your accountโ€™s secret key, it is available under Tools โ†’ General Settings

Verifying rewarded callbacks on the publisher server ๐Ÿ”—

When a rewarded ad is shown, Mediation will ping your serverโ€™s endpoint. An example of a Body containing all the required macros:

   "tx": "%%TRANSACTION_ID%%",
   "usr": "%%USER_ID%%",
   "sdk": %%SDK_TIMESTAMP%%,
   "svt": %%SERVER_TIMESTAMP%%,
   "hash": "%%VERIFICATION%%"

When you receive the callback, you can verify that the request is authentic by regenerating the %%VERIFICATION%% hash with the following method:

  SHA256(secret_key, message)

Note that the secret key will be the same value available from Tools in the Dashboard. You will then need to verify that the result of the operation above equals the value of the %%VERIFICATION%% hash.

Bidding Settings ๐Ÿ”—

Adding Bidding Networks ๐Ÿ”—

Review our Partner Network Details chart for a complete list of available bidding networks and instructions on connecting their network with Chartboost Mediation.

  • Make sure the network partner credentials here exactly match the information in your account on each network dashboard.
  • Make sure all desired bidding networks are active.

Prioritize Bidding ๐Ÿ”—

Enabling this feature will consider and return the highest bid above the set prioritized bidding CPM price. If no bid above the CPM price is returned, then the CPM of waterfall line items and winning bids will be considered from highest to lowest to return an ad.

Using this feature may not get the best price for every impression since waterfall line items will not be considered unless no bids are available, even if you have a higher rate line item available. Therefore, we recommend utilizing this option if youโ€™re experiencing high latency or you have an extensive waterfall.

eCPM Floor ๐Ÿ”—

  • If you are using bidding only in this Mediation placement, you can enable eCPM floor by either setting a global floor or country-specific floors.
  • Country level eCPM floor takes precedence over the global eCPM floor. For any countries that donโ€™t have country level eCPM floor, the Mediation will use the global eCPM floor.
  • If you are using both bidding and waterfall in this Mediation placement, you should not enable eCPM floor, since you would want bidding partners to compete in all ad requests with non-bidding networks/line items.

Waterfall Settings ๐Ÿ”—

Each waterfall can contain a set of ad groups specific to an ad format type. Each ad group will contain a set of line items which is a specific partner network ad placement.

A single app can have multiple waterfalls for different use case needs.

To get started, click on + Add under Ad Groups and select + Create a new Ad Group. Existing ad groups can also be linked to this placement.

Ad Groups ๐Ÿ”—

  1. Give your ad group a Name that is easily identifiable for you.
  2. You cannot change the Type (Ad Format) of an ad group.
  3. Set the country list to target. To set a specific list of country, choose Include specified countries or Exclude specified countries in the dropdown. Then, in the Select Country dropdown, select the country to include/exclude and click the + button.

Line Items ๐Ÿ”—

Line Items are specific to a partner network. Review our Partner Network Details chart for a complete list of available waterfall networks and instructions on connecting their network and partner placement with Chartboost Mediation.

Make sure your line items are added to the group.

  1. Click + Add a line item to bring up existing line items.
  2. Check the Add to Ad Group box in the network partner placements row.
  3. Click + Add Selected Items button on the bottom right corner