Swelen Labs

Swelen Android SDK

With Loodies™ Ad Formats - Last Build: 2.1.7 - 08/01/2014

Download

Swelen Android SDK - Build 2.1.7

Requirements

SDK installation

Adding the SDK JAR to your Java project

Download the latest Android SDK and unzip it.

If you are using Eclipse:
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">
    <uses-sdk android:targetSdkVersion="4" />
    <application android:label="@string/app_name" android:hardwareAccelerated="true" >
        <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/Update the uses-sdk tag and enable hardware acceleration

You need to :

<?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">
    <uses-sdk android:targetSdkVersion="4" />
    <application android:label="@string/app_name" 
                 android:hardwareAccelerated="true">
    ...
    ...
    </application>
</manifest>
        

For more information about the uses-sdk tag, you can read the Android documentation

Add permissions to your AndroidManifest.xml

The following permissions must be added 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">
    <uses-sdk android:targetSdkVersion="4" />
    <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" />
</manifest>
        

Displaying ads

Fixed ads

Fixed ads are displayed by a custom view: SwelenAdView. To display an ad your need to:
Note : the SwelenAdView must be instantited on the UI thread
Additionally you'll have to call the methods : pause, resume, destroy of SwelenAdView in respectively methods : onPause, onResume, onDestroy of your Activity.
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: 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:
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 the third argument to true. That way the SDK will fetch user geolocation for you.
            SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, true);
        
You can also pass a Location object. The user's Location must be obtained by a suitable method.
            SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, location);
        
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: 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);
        

Allow immediate closing of interstitials

If you want to allow your users to close an interstitials ad at any time - even if it has a countdown - you can use the method userCanCloseAfterDisplay(boolean canClose);
            SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, location);
            adView.userCanCloseAfterDisplay(true);
        

Automatic refresh for fixed ads

You can automatically refresh fixed ads by calling setAutoRefresh(boolean autoRefresh); method of SwelenAdView. The ads will be refreshed each 20 seconds.
            SwelenAdView adView = new SwelenAdView(this, YOUR_SLOT_UID, location);
            adView.setAutoRefresh(true);
        

Conversion Tracking

Example: Track application downloads

Conversion tracking is done in two simple steps:
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:

Conversion tracking events

You may optionally track conversion events. The following listeners are available:
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);
    } 
}

Conversion tracking with amount and currency

Additionally you can also define an amount along with a currency for the conversion. The currency must be in ISO 4217 format.
SwelenAdConversion conversion = new SwelenAdConversion(this, YOUR_CONVERSION_UID, SwelenAdConversion.UNIQUE, "USD", 4.25);
        

External SDK support

Swelen SDK can also display AdMob banners, Millennial Media or InMobi banners and interstitals if no Swelen ads are available.

Requirements

To display ads from these networks you have to :

AdMob (Google Play Services SDK)

For AdMob, setup the Google Play Services SDK, following the guide at : http://developer.android.com/google/play-services/setup.html

InMobi and MillennialMedia