Swelen Android SDK

With Loodies™ Ad Formats - Last Build: 2.0.5 - 2012/02/22

Download

(status: beta)

Requirements

Android 1.5 or later.
Swelen Android SDK for Swelen Magnet and MobileManager (obviously).
Your slot UID from Swelen: To find your slot UID, log into your Swelen account, select "Applications" then click on your application.

SDK installation

Adding the SDK JAR to your Java project

Download the latest Android SDK and unzip it.

If you are using Eclipse:

Right click on you app project and choose "Properties"
Select "Java build path"
On the right panel choose the "Librairies" tab and click the "Add external Jars" button.
Navigate to SwelenAds.jar and select it.

Note: If your not using Eclipse, you can put SwelenAds.jar in the libs directory of your project.

Declare com.swelen.ads.SwelenAdActivity to your AndroidManifest.xml

The SDK requires com.swelen.ads.SwelenAdActivity to be declared with the theme Theme.Translucent in your AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.swelends.ads.example"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:label="@string/app_name" >
        <activity android:name="SwelenAdsExample"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity android:name="com.swelen.ads.SwelenAdActivity"
                android:theme="@android:style/Theme.Translucent"
                android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"/>
    </application>
</manifest>

Add permissions to your AndroidManifest.xml

The following permissions must be added in your AndroidManifest.xml:

android.permission.INTERNET
android.permission.ACCESS_NETWORK_STATE
android.permission.READ_PHONE_STATE

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.swelends.ads.example"
      android:versionCode="1"
      android:versionName="1.0">
    <application android:label="@string/app_name" >
        <activity android:name="SwelenAdsExample"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <activity android:name="com.swelen.ads.SwelenAdActivity"
                android:theme="@android:style/Theme.Translucent"
                android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"/>
    </application>
	<uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
</manifest>

Displaying ads

Fixed ads

Fixed ads are displayed by a custom view: SwelenAdView. To display an ad your need to:

Import com.swelen.ads.SwelenAdView
Instantiate a new SwelenAdView with your slot UID
Add the view to the UI

Additionally you'll have to call the methods : pause, resume, destroy of SwelenAdView in respectively methods : onPause, onResume, onDestroy of your Activity. This is needed for video ads to stop playing if your app is paused.

The following sample app demonstrates how you can instanciate fixed ads:

import android.app.Activity;
import android.os.Bundle;
import android.widget.LinearLayout;

import com.swelen.ads.SwelenAdView;

public class SwelenAdsExample extends Activity
{
	private SwelenAdView adView;

	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.main);

		//Instantiate a new SwelenAdView
		adView = new SwelenAdView(this, YOUR_SLOT_UID);

		//Lookup your layout, assuming it's been given the attribute android:id="@+id/mainLayout"
		LinearLayout layout = (LinearLayout)findViewById(R.id.mainLayout);

		//Add the SwelenAdView to your layout
		layout.addView(adView);
	}

	@Override
	public void onDestroy() {
		super.onDestroy();
		adView.destroy();
	}

	@Override
	protected void onResume() {
		super.onResume();
		adView.resume();
	}

	@Override
	protected void onPause() {
		super.onPause();
		adView.pause();
	}
}

Overlay ads

Overlay ads are loaded by a custom view : SwelenAdView. When assets are loaded, it starts SwelenAdActivity and then the ad is displayed. To display an overlay ad you need to:

Import com.swelen.ads.SwelenAdView
Instantiate a new SwelenAdView with your slot UID

Additionally you'll have to call the method : destroy of SwelenAdView in the onDestroy method of your Activity.

The following sample app demonstrates how to implement overlay ads:

import android.app.Activity;
import android.os.Bundle;
import android.widget.LinearLayout;

import com.swelen.ads.SwelenAdView;

public class SwelenAdsExample extends Activity
{
	private SwelenAdView adView;

	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.main);

		//Instantiate a new SwelenAdView
		adView = new SwelenAdView(this, YOUR_SLOT_UID);
	}

	@Override
	public void onDestroy() {
		super.onDestroy();
		adView.destroy();
	}
}

Note: When overlay ads are displayed, a new activity is started by SwelenAdView. It will be displayed on top of your activity with translucent theme.

Advanced features

Intercepting ad events

You may optionally track ad events like : loading failures, displaying ad, clicking on the ad and more. You can do it by implementing com.swelen.ads.SwelenAdListener in an object you pass to SwelenAdView.setAdListener.

The following listeners are available:

public Boolean onAdLoaded(SwelenAdView v);
Sent when SwelenAdView finished loading the ad. If this method return true the ad is immediatly displayed, otherwise the ad will be displayed by calling the display() method of SwelenAdView
public void onAdError(SwelenAdView v, int error);
Sent when the ad failed to load, the error arguments may take the following values:
- SwelenAdView.ERR_CANT_CONNECT : Failed to connect to swelen ad server (network down, timeout, ...)
- SwelenAdView.ERR_BAD_DATA : Data received from Swelen AdServer are incorrect
- SwelenAdView.ERR_NO_AD_FOUND : No ad found for your slot UID
- SwelenAdView.ERR_LOADING_ASSETS : Error while loading ad assets
public void onAdShow(SwelenAdView v);
Sent when the ad is displayed.
public void onAdClose(SwelenAdView v);
Sent when the ad is closed.
public void onAdClick(SwelenAdView v);
Sent when the user click on the ad.

import android.util.Log;
import android.app.Activity;
import android.os.Bundle;
import android.widget.LinearLayout;

import com.swelen.ads.SwelenAdView;
import com.swelen.ads.SwelenAdListener;

public class SwelenAdsExample extends Activity implements SwelenAdListener
{
    private SwelenAdView adView;

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

		//Instantiate a new SwelenAdView
        adView = new SwelenAdView(this, YOUR_SLOT_UID);
		
		adView.setAdListener(this);

		//Lookup your layout, assuming it's been given the attribute android:id="@+id/mainLayout"
        LinearLayout layout = (LinearLayout)findViewById(R.id.mainLayout);

		//Add the SwelenAdView to your layout. 
        layout.addView(adView);
    }

    public Boolean onAdLoaded(SwelenAdView v) {
        Log.d("DemoDebug", "onAdLoaded called");
        return true;//Display the ad right away
    }

    public void onAdShow(SwelenAdView v) {
        Log.d("DemoDebug", "onAdShow called");
    }

    public void onAdError(SwelenAdView v, int error) {
        Log.e("DemoDebug", "onAdError : " + error);
    }

    public void onAdClose(SwelenAdView v) {
        Log.d("DemoDebug", "onAdClose called");
    }

    public void onAdClick(SwelenAdView v) {
        Log.d("DemoDebug", "onAdClick called");
    }
}

Note: If you are planning to display video ads on applications that already use audio or video, please consider pausing them in SwelenAdListener.onAdLoaded

GeoTargeting

Location targeting can be done by instantiating SwelenAdView with a location argument :

        	SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, location);

The user's location must be obtained by a suitable method.

Important Notes about geotargeted mobile advertising :

Geolocation must not be used solely for geotargeted ads.
Geolocation should only be specified if that information is already used by your app.
Swelen does not record geolocation information on users.

Disabling auto closing on ads

Except for fixed ads, all other overlay ads will be automatically closed:

For videos ads: When the video finished playing.
For others ads: When the ad countdown is over.

You can change this behavior by calling the setAutoClose(Boolean autoclose); method of SwelenAdView

        	SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, location);
			adView.setAutoClose(false);

Conversion Tracking

Example: Track application downloads

Conversion tracking is done in two simple steps:

Import com.swelen.ads.SwelenAdConversion
Instantiate a new SwelenAdConversion with your conversion UID and the conversion mode

import android.app.Activity;
import android.os.Bundle;
import android.widget.LinearLayout;

import com.swelen.ads.SwelenAdConversion;

public class SwelenAdsExample extends Activity
{
    private SwelenAdView adView;

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
		SwelenAdConversion conversion = new SwelenAdConversion(this, YOUR_CONVERSION_UID, SwelenAdConversion.UNIQUE);
    }
}

The following conversion modes are available:

SwelenAdConversion.UNIQUE : the conversion will be registered only one time
SwelenAdConversion.MULTIPLE : the conversion will be registered each time

Conversion tracking events

You may optionally track conversion events. The following listeners are available:

public void onAdConversion();
Sent when a conversion is successful.
public void onAdConversionError(int error); Sent when a conversion failed. The error arguments may take the following values:
- SwelenAdView.ERR_FAILED : Conversion refused by Swelen AdServer. This happend most of the time when your conversion UID is incorrect.
- SwelenAdView.ERR_CANT_CONNECT : Failed to connect to Swelen AdServer (network down, timeout, ...)

import android.util.Log;
import android.app.Activity;
import android.os.Bundle;

import com.swelen.ads.SwelenAdConversion;
import com.swelen.ads.SwelenAdConversionListener;

public class SwelenAdsExample extends Activity
{
    private SwelenAdView adView;

    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
		SwelenAdConversion conversion = new SwelenAdConversion(this, YOUR_CONVERSION_UID, SwelenAdConversion.UNIQUE);
		conversion.setListener(this);
    }

    public void onAdConversion() {
        Log.d("DemoDebug", "Conversion done!");
    }   
    
    public void onAdConversionError(int error) {
        Log.d("DemoDebug", "Conversion error : " + error);
    } 
}