How to integrate AdBuddiz advertisements SDK with Kivy application deployed to Android device

This article will show you how to implement AdBuddiz advertisement system in your Kivy application.

1. SDK download and opening documentation

First, you need to create an account at AdBuddiz. After that step, you can download AdBuddiz SDK. Now just extract the JAR file from the downloaded SDK ZIP file and put it in the /libs directory of your Kivy project. Once you add your first application (in the AdBuddiz control panel), you can get the API key. You don't need to publish it on the Google Play store right away, just type the package name and click "Ok", then "Continue" in the error message. You will have to click "Refresh app information" once the app is published and accessible through the main website.

Next step is to open AdBuddiz documentation. It will help you understand the code.

2. Add the correct permissions and settings to your buildozer.spec file

android.permissions = INTERNET,ACCESS_WIFI_STATE,ACCESS_NETWORK_STATE

ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE are optional. Without them, you might get less ads and tracking could be less accurate.

(uncomment this line)

android.add_jars = %(source.dir)s/libs/*.jar

3. Add the AdBuddiz Activity to your project's AndroidManifest.tmpl.xml file: (it should be somewhere inside python-for-android/dist/your_project_name/templates/)

<activity android:name="com.purplebrain.adbuddiz.sdk.AdBuddizActivity" 
               android:theme="@android:style/Theme.Translucent" />

A good place to put the code is just before the org.renpy.android.PythonActivity declaration.

4. Import pyjnius autoclass module in your main.py

from jnius import autoclass

5. Use autoclass() to access classes of your app's activity and AdBuddiz class

PythonActivity=autoclass("org.renpy.android.PythonActivity")
AdBuddiz=autoclass("com.purplebrain.adbuddiz.sdk.AdBuddiz")

6. Finally: use the accessed classes to initialise the SDK, load the Ads cache and show Interstitial Ads

You should request to cache ads as soon as your app starts with the following code:

AdBuddiz.setPublisherKey("TEST_PUBLISHER_KEY") # Replace with your real app key
AdBuddiz.setTestModeActive() # Comment this line before releasing!
AdBuddiz.cacheAds(PythonActivity.mActivity)

Before releasing the application you need to replace the test API key with your actual key and disable test mode. Keep test mode enabled while testing, as repeated installations on the same device are against their terms of use.

Whenever you want to display an ad, call showAd(). We recommend this call be made where there is a natural break in play like between levels for example.

AdBuddiz.showAd(PythonActivity.mActivity)

If you want to make buildozer rebuild your app, install it on your test device, run it and display only the most relevant logcat messages (debug messages with AdBuddiz and python tags, silence the rest), you can do all the steps in a single command:

$ buildozer android debug deploy run; adb logcat -s AdBuddiz:D python:D

7. Additional tips

You may notice some messages like these:

I/python  (17950): [INFO              ] [Android     ] Must go into sleep mode, check the app
I/python  (17950): [INFO              ] [Android     ] App doesn't support pause mode, stop.
I/python  (17950): [INFO              ] [Base        ] Leaving application in progress...

This happens because the interstitial ad is a full activity, Android will pause your PythonActivity, and since you haven't declared the on_pause method, it will stop the app. A good idea would be to implement the following methods inside your App class (customize them as needed):

    def on_pause(self):
        return True
    def on_resume(self):
        pass

then you can expect to see this instead:

I/AdBuddiz(20844): showAd
I/python  (20844): [INFO              ] [Android     ] Must go into sleep mode, check the app
I/python  (20844): [INFO              ] [Android     ] App paused, now wait for resume.
I/AdBuddiz(20844): LaunchRequest : UpdateConf
I/AdBuddiz(20844): LaunchRequest : AdImpression
I/AdBuddiz(20844): Request Ok : AdImpression
I/AdBuddiz(20844): Request Ok : UpdateConf
I/python  (20844): [INFO              ] [Android     ] Android has resumed, resume the app.
I/python  (20844): [INFO              ] [Android     ] App resume completed.

More details available here and here.

8. Simple App with the AdBuddiz usage example

from kivy.app import App
from kivy.uix.button import Button

from jnius import autoclass

from kivy.utils import platform

if platform=="android":
    PythonActivity=autoclass("org.renpy.android.PythonActivity")
    AdBuddiz=autoclass("com.purplebrain.adbuddiz.sdk.AdBuddiz")

class TestAdBuddizApp(App):
    def build(self):
        return Button(text="Show ads", on_press=self.show_ads)
    def on_start(self):
        AdBuddiz.setPublisherKey("TEST_PUBLISHER_KEY") #replace the key with your app Key
        AdBuddiz.setTestModeActive() #test mode will be active
        AdBuddiz.cacheAds(PythonActivity.mActivity) #now we are caching the ads
    def show_ads(*args):
        AdBuddiz.showAd(PythonActivity.mActivity) #let's show the ad ;)
    def on_pause(self): #save your app state here
        return True
    def on_resume(self):
        pass
		
if __name__=="__main__":
    TestAdBuddizApp().run()