1 Prerequisites
2 Step Summary
3 Initialize the SDK
4 Tagged wrappers
5 Events
- 5.1 Example of transition:
- 5.2 Example of button press:
6 Adding testing single tag data
7 Go into production
8 How does it works?

Prerequisites

Do Android Get Started all the way until finishing step 3

Step Summary

Add the Initialization code.
Add the Application class to the Manifest (in case you are using it)
Add the Tagged Wrappers, Tagged Buttons
Note the Transitions Events
Add the testing Single Data
Test everything is working
Change everything to production code
Your app is now prepared for monetization with us.

Initialize the SDK

We require the SDK to be initialized only once and as early as possible so for this purpose using Android’s application class is recommended but if your app only has one activity, if using the activity make sure it is never destroyed unless killing the app or placing it in the background, matching then the lifecycle of Application, you can initialize it in onCreate method of that Activity.

Let’s see the recommended method.

Create an Application class and add it to the manifest code to start the app with the Application class.

class Application: Application()
{
    override fun onCreate()
    {
        super.onCreate()
        
		R89SDK.setDebug() //This is for testing purposes, remove it on prod
		R89SDK.setLogLevel(LogLevels.DEBUG) //This is for testing purposes, remove it on prod
		
		addTestingSingleTagData() /* This is a later step */
		
		R89SDK.initialize(
			appContext = this,
			publisherId = "TestRefinery89ID", /* This is for testing purposes, change it on prod */
			appId = "TestDemoApp", /* This is for testing purposes, change it on prod */
			singleLine = true,
			initializationEvents = null
		)
    }
}

Your publisherId and appId will be provided to you during onboarding process by email, you can also retrieve them from the web interface after login.

This appID is not the same as the Manifest App Id you used in previous steps

Then add this application class to the manifest you already had from the Android Get Started.

The code for adding the application is the following

Remember that the ".Application" depends on the name of the class. If we named the class MyApplication we would need to put “.MyApplication"

<manifest>
    <application
        android:name=".Application">
    </application>
</manifest>

With this addition your full manifest should look like so:

This is a simplified example, you should have many more lines in the manifest, copy the important bits only.

<manifest>

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
    
    <application
        android:name=".Application">
    
    <!-- This is the Sample App ID-->
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-3940256099942544~3347511713"/>
        
    </application>
</manifest>

We will come back to this Application class to add our testing single tag data, but let's first add the tagged wrappers and events

Tagged wrappers

Tagged Wrappers are the container inside which the ads will show, they are normal wrappers with the android:tag attribute set. You need to add as many as you can, remember that placing a tagged wrapper does not mean we need to use it.

Check both https://refinery89.atlassian.net/wiki/x/A4DcSQ and Android Tagged Wrappers for more information

We recommend you add the wrappers using XML Views, since it’s easier than creating them using code, so something like this:

# activity_main.xml
...
<LinearLayout
    android:id="@+id/ad_container"
    android:tag="main_activity_bottom_ad_container"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:orientation="horizontal"
    android:layout_centerHorizontal="true"
    android:layout_alignParentBottom="true">
</LinearLayout>
...

With this added to your views we can detect that tag and place an ad inside of it if the single tag data says so.

Events

Events can trigger other formats, right now the single tag supports:

Transitions events are detected by the single tag automatically after initialization. They happen when an activity or fragment is started from other activity or fragment.
Button Presses when a button is pressed, this works They are detected by adding the android:tag attribute to the button.

Example of transition:

class MainActivity : AppCompatActivity()
{
	override fun onCreate(savedInstanceState: Bundle?)
	{
		super.onCreate(savedInstanceState)
		setContentView(R.layout.activity_main_auto)
		
		findViewById<Button>(R.id.goToNewsPost).setOnClickListener {
			val intent = Intent(this, NewsPostDetailActivity::class.java).apply {
				putExtra("newsPostData", newPostData)
			}
			startActivity(intent)
		}
	}
}

In this example an interstitial would be triggered when we see the NewsPostDetailActivity comes to live after loading.

Example of button press:

with this button code

# activity_main.xml
...
<Button
    android:id="@+id/play_video_trailer"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:tag="play_video_trailer_tag" />
...

class MainActivity : AppCompatActivity()
{
	override fun onCreate(savedInstanceState: Bundle?)
	{
		super.onCreate(savedInstanceState)
		setContentView(R.layout.activity_main_auto)
		
		findViewById<Button>(R.id.playVideoTrailer).setOnClickListener {
			playVideoTrailer()
		}
	}
}

In this example an interstitial would be triggered when the button is pressed and when the interstitial is closed the playVideoTrailer() method will be executed.

Adding testing single tag data

Go back to the application class that was created at the start of the guide, we are going to test all the transitions, tagged wrappers and tagged buttons you have placed in the app.

Before initialization method we called addTestingSingleTagData() that uses the SingleTagConfigBuilder to create the testing data needed for debugging the sdk.

More info in → Android How to test Single Tag Implementation

When using the SingleTagConfigBuilder you are not going to be able to select the ad units that are for production, they are by default the testing config id in Android - Ad Formats.

fun addTestingSingleTagData()
{
    //Add a Screen that is an Activity, the screenName you can get it by logging this in you code -> 
    // MainActivity::class.simpleName -> MainActivity
    // NewsPostDetailActivity::class.simpleName -> NewsPostDetailActivity
    
    val screenBuilder = SingleTagConfigBuilder.addAdScreenBuilder(
        isFragment = false, 
        screenName = "MainActivity"
    )
    
    // Add a banner format to the wrapper with the tag main_activity_bottom_ad_container
    screenBuilder.addBanner(
      wrapperTag = "main_activity_bottom_ad_container", 
      getAllWithTag = false, /* Only the first tagged wrapper in "MainActivity" with this tag will be used for this banner*/
      wrapperRelativePositionInside = true /* the ad will be placed inside of the wrapper */
    )
    
    /* trigger interstitial when we transition from "MainActivity" (ScreenBuilder.screenName) TO NewsPostDetailActivity */
    screenBuilder.addInterstitial(
        eventsToTrackTo = "NewsPostDetailActivity", 
        eventsToTrackButton = null
    )
    
    /* trigger an interstitial when a button with this tag is pressed in "MainActivity" (ScreenBuilder.screenName) */
    screenBuilder.addInterstitial(
        eventsToTrackTo = null
        eventsToTrackButton = "play_video_trailer_tag" 
    )
}

This step is for testing purposes and you are only going to see test ads when using this approach, but this is very helpful to us if you provide this peace of code to tell us where you want to place the ads.

Later when in production, this code will be removed and you have hopefully added flexible tagged wrappers and tagged all the button as possible so we can change your ad slots from the server without the need of updating the app.

Go into production

For going into production you will need to use you ids:

Remove the methods R89SDK.setDebug() and addTestingSingleTagData()
Change the App id in the manifest for the production one
Change the appId and publisherId in the initialization method for the production ones
it’s also recommended to remove R89SDK.setLogLevel(LogLevels.DEBUG) but not needed

How does it works?

We monitor your app to determine the active screen at any given moment. For each screen, we maintain a record of events and tags that you have supplied, enabling us to place ads in those tagged views or during specific transitions and events from the record.

We have the capability to display Display ads on a tagged wrappers or trigger an Interstitial ads during the transition from one screen to another or in button press. And many other things All of this can be achieved without the need of coding specific triggers or manually adding the ad to the view. It is as simple as initializing the SDK.

SDK Public Documentation

Android Single Tag Implementation