Menu

Introduction to Shared Placement

In order to optimize developer revenue, TopOn provides a shared placement mechanism, which allows placements to be loaded and displayed. In addition to the original ad pool, ad content can be obtained from the shared cache pool, thereby increasing placement filling and raising placement prices.

1. Function Introduction

  • Shared Placement can be enabled with one click or added manually on the [application]  page. Only shared placement of the same ad type are supported.
  • After all placements of the same style are connected to the shared pool, they will share the same shared placements.
  • When developers call a placement that has been connected to the shared pool, they will compare the price of the original placement with the shared placement and select the higher-priced one for display.
  • There are two functions for shared placement:

1. Main Placement+shared Placement high price pool, improve ECPM
Add a Shared Placement, associate multiple Main Placement to the same Shared Placement, when the Main Placement is loaded, the Shared Placement is loaded at the same time, when the Shared Placement has cached high-priced ad sources, the APP can display higher-priced ad sources, and increase the revenue of the placement. The diagram is as follows:

2. Main Placement+Shared Placement bottom pool, improve fill rate
When the fill rate of the Main Placement is low, you can choose to configure the waterfall flow to be consistent with the Main Placement, and supplement the fill rate when the Main Placement is not filled, thereby improving IPU.

 

2. Instructions for use

  • If you need to support the share placement strategy, there is no need for additional client code development. You only need to update Taku SDK v6.2.20 and above and perform relevant configuration in the background. Currently, this function is a whitelist mechanism. If you need to use it, please contact Taku account manager to activate it.

    If placements are checked in the client callback interface or S2S incentive callback interface, compatibility processing must be performed according to the following document .

  • The entire background configuration process only requires two steps:

    1. Select placements to access the shared pool
    2. Configure Waterfall for Shared Placements

The specific steps are as follows:

2.1. Select placements to access the Shared Placement

2.1.1 Directly turn on the Shared Placement switch in the Main Placement

  1. Open the application page
  2. Select the placement you want to access the shared placement and turn on the switch

Choose to add or access existing shared placements based on different scenarios

① By default, select Add Shared Placement, fill in the name of the shared palcement and create the binding normally. It is recommended that you include the [Shared Placement] field when naming to facilitate subsequent data viewing

② If there is already a shared palcement, you can choose to access the existing shared palcement. By default, only the shared palcement of the current ad type is displayed (applicable to scenarios where multiple main palcement are connected to the same shared palcement)

 

2.1.2 Manually add shared placement

In [Application]- Shared Placement  List, you can manually add shared placement.

After selecting the ad type, only placement of the corresponding ad type can be selected for the connected main placement. Note: The enabled shared placement must be connected to the main placement.

Supports specifying the effective application version number for shared placements. It will be matched exactly according to the filled content. It is recommended to consult App R&D technology to provide the application version number; rule: >= specified version number. If not filled, all version numbers will be effective by default. Android: fill in a positive integer; iOS: the version number can only be a combination of numbers and ".";

 

2.1.3 Share Placement Management

After adding a shared placement successfully, you can check which shared placement the current main placement is connected to on the [Application]  page;

You can also display all shared placements of the current application, their status and binding relationships on the [Shared Placement] page.

 

2.2. Configure Waterfall for Share Placements

After adding a shared placement successfully, if the shared placement has not been configured with any ad source, a reminder will be displayed:

In order to fully use the shared placement function and give full play to the role of the shared pool, please go to the mediation page to configure the corresponding ad source for the connected shared placement. The specific process is as follows:

1. You can select shared placements on the mediation page to set up waterfall.

 

2. Shared placement waterfall settings suggestions:

According to the positioning of shared placement, you can use a combination of ordinary space + shared high-price pool to raise ecpm; you can also use a combination of high-price + shared bottom pool to increase the fill rate.

  1. Since the loading timing of shared placements is different from that of ordinary placements, in order to avoid affecting the filling of the original placements, it is recommended to use additional ad sources for shared placements.
  2. If the shared placements are used as a high-price pool , it is recommended to set up high-price ad sources in a densely cross-section in the shared placements, reserve several medium-price ad sources, and set the number of parallel requests to 1 (i.e. serial request); for ordinary placements connected to the shared pool, set up medium and low-price ad sources normally, and reserve several high-price ad sources sparsely.
  3. If the shared placement is used as a backup pool , it is recommended that the waterfall structure be the same as the ordinary placement, and the number of caches opened is 2, the number of parallel entries is set to 2, and more bidding sources are opened.

 

2.3 Recommended waterfall configuration for Shared Placement

We provide a function to recommend configurations for shared placements. Through algorithms, we can quickly help you automatically generate waterfall configurations for shared placements based on the data of the main placements currently connected to the shared placements.

You can view this by clicking on the recommended configuration entry on the [Mediation] management page.

Select the content that needs to be configured according to the configuration process. The current application needs to have an network bound to it. It is recommended that you enable the function of automatically creating ad sources.

 

3. View Shared Placement data

If you need to view the data of shared placements , you can go to the full report , filter the placement dimension, and view the placement data in the format of " Shared_Ad Type_Application UUID "; Or search for keywords for the shared placements you created.

It should be noted that after the original placement is connected to the shared pool, the original placement will be compared with the shared placement, and the higher-priced one will be selected for display. When the price of the original placement is low, the display opportunity will be given to the shared placement. Therefore, the impression rate of the placement connected to the shared pool may be reduced. If you need to view the impact of the overall impression rate, it is recommended to filter the application + ad type dimension to view the overall data.

 

4. Shared Placement compatibility changes

If the developer has verified the placement in the client callback interface or S2S incentive callback interface, the developer needs to refer to the following document to make compatible processing for the shared placement.

If the placement in the callback information is not verified, no additional processing is required and the shared placement function can be used normally.

4.1 Android SDK callback processing

If a shared placement is displayed, a shared placement field will be added to the callback interface, passing the shared placement ID; the placement field passes the real placement ID. The callback information involved is as follows:

ATAdInfo callback information description

method Return value type illustrate
getTopOnPlacementId() String Get the TopOn placement ID
getSharedPlacementId() String Get the shared placement ID. If the shared placement is displayed, this method returns the shared placement ID.
getPlacementType() int Get the placement type. The enumeration values are as follows:
ATAdConst.ATPlacementType.NORMAL: Normal & real placement
ATAdConst.ATPlacementType.SHARED: Shared Placement

If the developer wants to verify the placement, it is recommended to first determine whether getSharedPlacementId() is a shared placement. If not, get getTopOnPlacementId().

ATAdInfo callback information description

 

4.2 iOS SDK callback processing

If a shared placement is displayed, a shared placement field will be added to the callback interface, passing the shared placement ID; the placement field passes the real placement ID. The callback information involved is as follows:

ATCheckLoadModel callback information description

key Return value type illustrate
shared_placement_id String Get the shared placement ID. If the shared placement is displayed, the shared placement ID will be called back
adunit_id String Get the placement ID of the ad platform

If the developer wants to verify the placement, it is recommended to first determine whether the shared_placement_id is a shared placement display. If not, obtain the adunit_id.

ATCheckLoadModel callback information description

 

4.3 Incentive Video Server Incentive (S2S) Processing

If a shared placement is displayed, the real placement field will be added to the callback interface, and the original placement ID will be passed; while the placement field will pass the shared placement ID. The fields involved are as follows:

Callback URL parameter information description

parameter illustrate
{placement_id} Get the placement ID of the TopOn ad platform
{share_placement_id} Get the shared placement ID. If the shared placement is displayed, the shared placement ID will be called back

If the developer wants to verify the placement, it is recommended to first determine whether {share_placement_id} is a shared placement. If not, obtain {placement_id}.

TopOn server incentive callback information description

 

5. Create AB experiment with shared placement in one click

If you want to use AB experiments to test the performance of shared placements, you can configure the experiment through the smart [Shared placement experiment] in [placement AB test].

After the main placement is connected to the shared placement, its own display and revenue will be reduced. In order to view the overall data effect, it is recommended that you check the main placement and the corresponding shared placement at the same time when conducting AB testing.

You can also use the function of automatically checking the shared placement and the main placement, as shown in Figure 1 below

After checking the automatic experiment, the configuration of the experiment group will be automatically adjusted for you, and automatic modification is not supported.

Experimental principle: The experimental group will enable shared placements, while the control group will not enable shared placements.

The effect after submission is as follows, and two experiments will be created.

 

6. One-click creation of Shared Placement + AB Experiment(recommended)

You can use our shared placement recommendation configuration function directly without creating a shared placement. We will automatically create a shared placement for you and configure the AB experiment for the shared placement.

View the document for detailed guidance: Shared Placement Recommended configuration function

 

7. FAQ

(1) When will share placement be used?

Answer: When the original placement is called load(), isReady(), and show(), the associated shared placement will be queried for price comparison; when the cache number of the shared placement is lower than the threshold, TopOn SDK will automatically load the ad source of the shared placement.

(2) Can I control shared placements through SDK methods?

Answer: No.

The shared placements automatically created by the system cannot be independently controlled by the developer through the interface, and can only be automatically called and used by the TopOn SDK according to the usage scenario. If the shared placement is called incorrectly, the error code 10009 will be returned (for specific error information, please refer to the "Error Code Description" ).

If developers need to adjust the calling strategy of shared placements, they can contact TopOn account managers for processing.

(3) Can share placements be used to set up segments and conduct ab experiments?

Answer: Yes.

(4) How do I set up an A/B experiment to compare the effectiveness of using shared placements?

A: You can configure the same a/b experiment grouping for the original placement and the shared placement, where the shared placement experimental group is configured with Waterfall, while the control group is not configured with Waterfall. Finally, you can filter the "application" + "ad type" + "a/b test" dimensions in the full report to compare the data.

(5) When displaying native ads that shared placement, the width and height of the ads are abnormal.

A: Please refer to the following code for setting up:

Note: The width and height specified in localExtra must be consistent with those set before the native ad request in ATNative.setLocalExtra(localExtra).

  • Android
Map<String, Object> localExtra = new HashMap<>();
localExtra.put(ATAdConst.KEY.AD_WIDTH, adViewWidth);
localExtra.put(ATAdConst.KEY.AD_HEIGHT, adViewHeight);

ATSDK.setSharedPlacementConfig(new ATSharedPlacementConfig.Builder().nativeLocalExtra(localExtra).build());

ATSDK.init(this, "Your App ID", "Your App Key");
  • iOS
#pragma mark - SharePlacement
- (void)setSharePlacementConfig {
    NSMutableDictionary *nativeLoadExtra = [NSMutableDictionary dictionary];
    [nativeLoadExtra setValue:[NSValue valueWithCGSize:CGSizeMake(300.0f, 200.0f)] forKey:kATExtraInfoNativeAdSizeKey];
    [nativeLoadExtra setValue:@"PPPPPP_native" forKey:kATAdLoadingExtraMediaExtraKey];
    //Same as normal Ad Setting
    [nativeLoadExtra setValue:@YES forKey:kATNativeAdSizeToFitKey];
    
    ATSharePlacementConfig *sharePlacementConfig = [[ATSharePlacementConfig alloc] init];
    sharePlacementConfig.nativeLoadExtra = nativeLoadExtra;
    [[ATAPI sharedInstance] setSharePlacementConfig:sharePlacementConfig];
}
 
Last modified: 2025-05-30Powered by