[Tutorial] How To Use AppBrain Remote Settings for Ad Network Mediation

Overview

Many people here (myself included) use AdMob Mediation to handle allocation of multiple banner ad networks. This service also supports interstitials, and allows you to integrate any number of ad networks using custom events.

But all of this can take a fair bit of work to set up. Sometimes all you need is a quick and easy solution, to choose between two different paths of code in your app. Here I’d like to demonstrate a simple mediation solution using the Remote Settings tool provided by AppBrain.

AppBrain Remote Settings

For those who aren’t already familiar with the service: AppBrain offers an SDK which developers can integrate into their apps. This SDK provides some basic stats about downloads and usage figures, which can be viewed through the AppBrain developer website. The SDK also offers an app wall which can be shown on exit.

What many people don’t know is that the SDK also has an additional feature. Developers can specify a number of settings (in the form of string-value pairs) on the AppBrain website. When the SDK is initialised, these settings are automatically synchronized to the phone’s local storage. They can then be accessed at any time (online or offline), using a simple function call. Click here to read more about the Remote Settings feature.

Example

Here’s a simple example. Let’s say we create an app, and add a setting via the web interface as follows:
[ul]
[li]Setting Name: “welcome_message”[/li][li]Setting Value: “Hello, World!”[/li][/ul]
Now within the app, we initialise the SDK using this function call:

AppBrain.initApp(this);

The remote settings will be downloaded and cached silently in the background. To use the setting somewhere else in the app, we can do something like this:

String welcomeMessage = AppBrain.getSettings().get("welcome_message", "Default text if setting not downloaded yet");
Toast.makeText(this, welcomeMessage, Toast.LENGTH_LONG).show();

If the setting has not been download yet, the default text will be returned. The SDK will only fetch remote settings once a day, so any further updates on the remote end will have to wait 24 hours before they are reflected in the app.
As you can see, this is a very simple and easy way to handle remote settings within your app.

Using Remote Settings For Mediation

Moving on from this example, let’s say you want to integrate app walls from both LeadBolt and SendDroid. It would be possible to write a custom event and use AdMob Mediation for this. But with AppBrain’s remote settings, it is much easier. Here’s how to do it.

[ol]
[li]Integrate the AppBrain SDK.[/li]To start, you’ll need to integrate AppBrain’s SDK by following these instructions. This includes calling init() in your activity’s onCreate() method.
[li]Integrate the two Ad Network SDKs.[/li]Next follow the integration instructions for whichever ad networks you want to use. This could include adding activities and permissions to AndroidManifest.xml, and also initialising the SDKs in your onCreate() method if required. Set it up as per the documentation, or however you normally integrate these networks.
[li]Decide the allocation percentage.[/li]For this example, let’s say we want to allocate 80% of traffic to LeadBolt, and 20% to SendDroid.
[li]Create the remote settings.[/li]Given the percentages above, define two remote settings in AppBrain:
[ul]
[li]Name: allocation_leadbolt[/li]Value: 80
[li]Name: allocation_senddroid[/li]Value: 20
[/ul]

[li]Decide which network to use at runtime.[/li]When you want to display an app wall, use the following code to decide between the two different networks.

// Get a random number <= 100
Random r = new Random();
Integer n = r.nextInt(100);

// Get the network allocations
Integer allocation_leadbolt = Integer.valueOf(AppBrain.getSettings().get("allocation_leadbolt", "50"))
Integer allocation_senddroid = Integer.valueOf(AppBrain.getSettings().get("allocation_senddroid", "50"))

// Choose which network to use
if (n <= allocation_leadbolt) {
    // Display LeadBolt App Wall
    // ...
} else {
    // Display SendDroid App Wall
    // ...
}

[/ol]
That’s it! You can use this code to easily switch between two different ad networks using AppBrain’s Remote Settings feature.

But hang on… you didn’t use the second allocation variable![SIZE=1][SIZE=2]

That’s right. In the example above I pulled in two remote settings, but only ended up using one of them (the LeadBolt allocation).

The reason I included the SendDroid allocation as a separate setting is because it’s really quite easy to expand this for 3, or 4 networks. You could do something like this:
[/SIZE][/SIZE]

// Choose which network to use
if (n <= allocation_leadbolt) {
    // Display LeadBolt App Wall
    // ...
} else if (n <= allocation_senddroid + allocation_leadbolt) {
    // Display SendDroid App Wall
    // ...
} else if (n <= allocation_airpush + allocation_senddroid + allocation_leadbolt) {
// Display Airpush App Wall
    // ...[SIZE=1][SIZE=2]
} else {
[/SIZE][/SIZE]// Display backup ads
    // ...[SIZE=1][SIZE=2]
}[/SIZE][/SIZE]

[SIZE=1][SIZE=2]
Of course, that code could be improved a lot. The use of multiple if/else-if statements is unweildy and doesn’t scale well. If you want to write a better version feel free to do so, and share it here! :slight_smile:
This example is simply designed to give you an idea of how powerful remote settings can be.

[SIZE=3]Conclusion

Hopefully this tutorial has helped you understand how AppBrain Remote Settings work, and how they can be used to switch between multiple ad networks dynamically. The SDK is very simple, you can use it pretty much anywhere you would like to switch between different code paths.

[/SIZE][/SIZE][/SIZE]Feel free to reply with any questions, comments or improvements to the code samples I’ve given. And let us all know about the creative ways you’re using remote settings in your app!

Wow, Wonderful tutorial, David!

Thanks David,) Just in time.

PS. To mention, that your last Else, I think will never be executed, as the rand numbers will be between 100 always, so you already put action between 100. So, dont need the last else…

Very helpful tutorial ,
Thank you @david
it is much needed this days considering the changes in the adnetworks eCPM each day

Anyone using AppBrain Remote Settings - here is some info which may reduce confusion regarding it’s use and it’s limitations (esp. when testing an app).

AppBrain AppLift SDK for Android apps - Monetization and Remote settings

QUOTE:

Note: The SDK fetches the settings at most once per day (when init is called), therefore it will use the old value if you have already started the app on this day. If you’re testing, you can use “Delete settings” in the Android settings page for your application to force a refresh, or uninstall and reinstall your app.

Basically, an app using AppBrain Remote Settings will try to minimize it’s connection to AppBrain servers - this is fine from AppBrain point of view, and in practice ALSO it is a reasonable choice (because in changing mediation settings it is usually not essential to get instant response - you can generally wait a day to see results - and you want to cut down on apps using too much internet bandwidth as well - though the showing of ads itself would probably be bigger than that !?).

However, this minimalistic connection schedule makes it problematic when testing apps - usually you have to “Clear Data” and “Force Close” the app to make sure it is not running and it’s earlier data is cleared - this essentially forces the app then to make a connection to AppBrain servers - and you will then see the results within your app.

This constraint also means that testing is complicated - as you cannot really test (in a fast way) various combinatios of settings changes and time elapsing etc. - as there is a third variable i.e. “how often does the app connect to AppBrain servers”.

A second variable is whether the app has successfully downloaded updated settings from the server - AppBrain would do good to provide such a method in the SDK - as it will help in some situations (as the app tries to make sense of the settings).

Note also - there can be a further point of confusion with Android Shared Preferences - “false” (boolean) settings are sometimes NOT saved in Shared Preferences (I encountered this issue when adding a “Preferences” or Settings menu item to an app). It was either related to Shared Preferences in general or to how Android Preferences class interacts with Shared Preferences.

So here are some rules of thumb when using AppBrain Remote Settings:

  • when your app queries AppBrain Remote Settings it may be retreiving yesterday’s settings (locally cached in Shared Preferences by AppBrain SDK) OR it maybe the new settings just downloaded by the app (there is no way to know)
  • often when you query settings - the first few times the SDK method will be returning old settings values (locally cached in Shared Preferences) - and say 10 seconds later (when new settings have arrived from a background download from AppBrain servers) when you query the settings you may get the new/fresh settings (as currently set at AppBrain webpage by you)

So for example, if you are using AppBrain Remote Settings for mediation for interstitial ads - your app may initially start showing interstitials (esp. any that you show very early in the session) based on yesterday’s or the default settings that are hardcoded in the app. But 10 seconds later the newest settings may arrive and then your mediation can start behaving according to the new settings.

This means that whenever you change settings on AppBrain webpage - their EFFECT will not be apparent to apps which are currently running or ran within last 24 hours etc. or so. Those will CONTINUE to use the settings they have gotten (as they don’t feel the need to update from AppBrain servers until the info is “stale” or older than 24 hours etc.).

THUS when you change AppBrain settings in the AppBrain webpage - it’s EFFECT will be only start to be seen for newly downloaded apps (or more precisely the newly run ones).

EVEN for the newly run apps - any behavior of the app for the first 10 seconds or so will be based on default settings and after that on the AppBrain server settings.

This means firstly - that if you want your ad mediation to be REFLECTIVE of the AppBrain Remote Settings (and not the default hardcoded settings that the app ships with i.e. “static final” variables or “50” etc.) - then you should NOT start to show ads immedaitely. Or more precisely if you WAIT say 10 seconds or such (for example you choose to not show ads until some time has passed) to show ads - then you can be reasonably sure that mediation results will reflect the AppBrain Remote Settings.

This means that if you THINK you are using AppBrain settings to do mediation of an ad that is shown at startup - it is almost NEVER going to behave according to the AppBrain Remote Settings - at least not on the first run. If anything, it will only behave according to new setting maybe if the user runs the app again on the next day or later !!

EDIT: note this may seem like a small thing “only the first run” - but for many apps the returning user rate is VERY LOW - in essence a MAJORITY of your user eyeballs are for FIRST INSTALL and RUNs of your app - and if your mediation fails on first run - a MAJORITY of your revenue will NOT be based on your finely tuned AppBrain Remote Settings - but the settings the app shipped with (i.e. hardcoded settings). This is UNACCEPTABLE behavior in terms of responsiveness.

So you can see that using AppBrain Remote Settings for mediation is possible and workable - but it is complicated slightly from what a developer with many things on their plate may THINK it should do …

Anyway, hope this helps.

Bottom line - if you can wait say 10 seconds or more before you start using AppBrain Remote Settings to make decisions within your app, then you can be REASONABLY sure that the behavior will be relfective of the CURRENTLY set settings on AppBrain. This is for new apps.

For apps which are run again and again the first day - remember that their behavior will not change in real-time as you tweak AppBrain Remote Settings - if anything they will only re-read from AppBrain servers after 24 hours etc.

Impact of this is that if you change AppBrain Remote Settings to accomplish a mediation proportion change from 50% admob 50% mmedia.com - to 100% admob 0% mmedia.com etc. - then any change you do now will only affect “everyone” (i.e. the returning users at least) after 24 hours.

So you change the settings - then you will get mixed results today - new downloads will be using new settings (after that 10 second caveat mentioned above) while returning users will continue to use settings from their previous run (if it was less than 24 hours ago). 24 hours later you can be pretty sure that both new downloads and returning users will be using the “new” AppBrain settings you changed today.

Hope this clarifies things.

This maybe belaboring the point, but there is a further caveat to remember for AppBrain Remote Settings - for uses such as ad mediation.

One needs to remember that a query of settings can change - i.e. be one thing in first few seconds of app, and something different after 10 seconds (as a new daily setting update is done with AppBrain servers).

Normally this is ok, but it can lead to some very odd errors that may not be apparent (rare means with thousands of users, you will get pissed off reviews about crashing app etc.).

For example an app may be written to query AppBrain Remote Settings to initialize certain ad networks (and not initialize others) in onCreate().

However 10 seconds later you may want to show an ad - and by that time new settings may have been retreived from AppBrain servers - at the time of display of ad you may think it is OK to display ad network A. However it may not have been initialized in onCreate (because at that time the app read yesterday’s cached settings).

So basically there can be a conflict between what different parts of your app thinks should be done - because they were initialized at different times.

This can lead to odd errors - which maybe hard to debug - for example you change AppBrain Remote Settings - and you get a certain number of errors that day (from users whose apps straddled that setting change).

For this reason you may want to take steps to ensure the value you use to decide things is set just once (local variable/flag). And to keep THAT current you may choose to delay that decision slightly (lazy) i.e. initialize a bit later (so decisions are based on newly retreived settings from AppBrain servers).

What would be great is if AppBrain provided a separate method for checking if “new” settings have just been received.
For example it already has an AppBrain.init() which you call so:
onCreate():
AppBrain.init();
Now add another method which essentially returns “true” if an update was received from AppBrain AFTER the call to AppBrain.init() was made.
boolean flag = AppBrain.receivedNewSettingsInThisAppSession();

EDIT: or returns the time-elapsed since init() was done before an update from AppBrain was received - if is minus - it would be before that etc.

NOTE: even the timestamp can be off in some situations - a phone whose battery was swapped will initially have a fictitious time - which is only set after it synchs with time server via internet. This could happen on android phones if the battery has run out and recharged and run. Though this may not be often - but for some types of apps - dealing with files and timestamps this could be critical that such a decision is made correctly.

Another tweak AppBrain could make would be to allow dynamic update of settings - this would mean millions of app sessions querying their servers (much more than the current once-a-day) but maybe that query returns just a timestamp of the last settings change on AppBrain servers. The app or AppBrain SDK could then make an intelligent decision whether they need to download the full XML describing the settings - or just get a partial XML.

For all I know AppBrain could ALREADY be doing this …