madvertise Android SDK (v3.1.2)

Intro

The madvertise Android SDK lets you monetize your Android apps via advertising. Basically, the code sends http requests to the madvertise ad server and displays banner and rich media ads in various formats.

Preparations

• Install Eclipse
• Install Android SDK and the ADT Eclipse Plugin
• Install Git
• Sign up at madvertise
  • If you don’t have already an account, please sign up.
  • Create an app and copy the token, it will identify the requests send to our ad-server.
  • The Sample SDK comes with its own token. You can use it during development and for testing.

• All code was tested with the latest Eclipse 3.7.1 (Build id: M20110909-1335) and ADT 12.0.0.v201106281929-138431

• The minimum Android SDK version is 7 (2.1).

Banner types and rich media (mraid) content

The madvertise Android SDK fully supports the mraid 1.0 standard. It can display text ads, static and animated banners and rich media media content, which means HTML5 and CSS animations. The SDK supports seven different banner_types (= sizes):

• mma 320×53
• medium_rectangle 300×250
• leaderboard 728×90
• fullcreen 768×768
• portrait 766×66
• landscape 1024×66
• rich_media up-to-fullscreen
  rich_media is a special format. With this banner_type, you provide your whole screen for the ad (e.g. on startup, between two levels in a game, …). It can only be used together with the parameter mraid = true and placement_type = interstitial. mraid is a boolen and decides, wheter you want mraid ads (html5 + css) or not. These ads take exactly the space given with the banner_type parameter. They can expand on a click and display animations (depends on the ad itself). The placement_type [interstitial|inline] is important, because the ad needs to know, how it is going to be displayed (inline, e.g. within a ListView, or interstitial as overlay above the other content). Please make sure, to set the placement_type parameter coresponding to your implementation, in order to get correct close buttons.

Using the SDK

For the impatient

• Clone this repository
• Add a new project with sources from [PROJECT_ROOT]/madvertiseSDK/ to your workspace
• Add the SDK to your project build path as described here
• Embed the MadvertiseView, e.g. like this : sample main.xml.
• Add permissions and the madvertise_site_token to your AndroidManifest.xml (sample : AndroidManifest.xml).

Step by Step

Once you have installed everything, open Eclipse and create a new Android Project. Use “Create project from existing source” and point the location to the sdk folder (/madvertise-android-sdk/madvertiseSDK). Adjust the compiler compliance level if you get warnings.

After your app project is created, you will need to add a reference to the Madvertise SDK for Android Project. Open the properties window for our app (File | Properties), select the Android item from the list, press the Add… button in the Library area and selecting the Madvertise SDK for Android Project created above.

Edit your AndroidManifest.xml file

1. Add internet permissions (INTERNET) and optionally location (ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION) and wifi state (ACCESS_WIFI_STATE).
2. Add meta data called madvertise_site_token
3. Add the Activity de.madvertise.android.sdk.MadvertiseActivity
4. Finally, your manifest file should look something like this

Prepare view configuration

1. Add a ressource file attrs.xml to the res/values folder of your android project
2. Copy the code to the file

Include the view that displays advertising banners

1. Add new namespace mad to your layout xml file
2. Add the MadvertiseView to your layout structure and configure it
3. The layout file should look similiar to this
4. You can create multiple of them, e. g. one fixed and another in a ListView. However, it is not recommended to use more than four of them.
5. IMPORTANT: You have multiple options to configure the view, requested banners, etc. (also see above in section Banner types and rich media (mraid) content)
   1. textColor [color], the color your text ad’s text should have. E.g. ‘#FFFFFF’.
   2. textSize [integer], the size of your text ad’s text. Maximum size is 20, minimum is 10.
   3. backgroundColor [color], the color the background of your text ads. E.g. ‘#000000’.
   4. secondsToRefresh [integer], the time after which a new ad will be loaded. Minimum is 45.
   5. bannerType [mma|leaderboard|fullscreen|portrait|landscape|medium_rectangle|rich_media], the ad type (size) of your banner. rich_media is a special high priced format that can cover the whole device screen. If rich_media is set, the placement_type is always (!) interstitial.
      The sizes are: mma 320×53, leaderboard 728×90, fullcreen 768×768, portrait 766×66, landscape 1024×66, medium_rectangle 300×250, rich_media up to fullscreen.
   6. animation [fade|left_to_right|top_down], the way new ads will be animated. ‘fade’ is default.
   7. deliverOnlyText [true|false], whether your ad only displays text or not. This only has effect on mma type banners.
   8. placement_type [inline|interstitial], only for mraid ads, default is inline. When declaring the placement_type as interstitial, you have to place your ad in a way that it is always visible, or, in other words, can not be scrolled out of the visible part of the screen. Basically interstitial ads do always have a close button, whereas inline ads might have none (if so, it’s provided by the ad itself).
   9. mraid [boolean], whether you want to display rich media ads or not, default is true. Please make sure to overwrite onApplicationPause() and onApplicationResume() in your MadvertiseCallbackListener appropriately when setting this flag to true. MRAID ads will have the initial size defined with the parameter “bannerType” (see above). They can expand on a click (expanded is defined by the ad itself, which might be fullscreen).

Using the SDK to track download conversions

The madvertise Android SDK allows advertisers to create a powerful link between ads running on the madvertise network and their own apps. The integration in your app is done by the following steps:

• Edit your AndroidManifest.xml file and add an intent filter within your main activity
  

  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myappname" />
  </intent-filter>

• IMPORTANT
  • Notice that andoid:scheme has to be unique to prevent interactions with other apps.
  • Do not use special chars or numbers as first char
• Add or create the following method in your main
  

  @Override
    protected void onResume() {
    super.onResume();
    // Report that the application was downloaded
    mTracker.reportDownload(getIntent(), "myappname"); // second param should be the same as android:scheme
  }

Sample App

The SDK comes with a very simple example, how to integrate the SDK in your APP. You can find it at [PROJECT_ROOT]/example/simple/.
Use “Create project from existing source” and point the location to the mentioned folder. You might get some compiler warnings. If so, adjust the compiler compliance level.

Please make sure to add the madvertiseSDK to the build path settings accordingly to your development environment.

For Eclipse with installed ADT Plugin follow these steps.

main.xml contains a MadvertiseView, that fetches the ads.

Contributing

1. Fork it.
2. Create a branch (`git checkout -b my_markup`)
3. Commit your changes (`git commit -am “Added Awesome Feature”`)
4. Push to the branch (`git push origin my_feature`)
5. Create an Issue with a link to your branch
6. Enjoy a refreshing Diet Coke and wait

About

madvertise is a mobile ad network, that enables developers to monetize their apps via advertising. Banners of various sizes can be placed on mobile websites or directly in applications. The latter is usually done with a SDK in form of a compiled library, that sends requests to an ad-server and display the mobile ad. So far, so good.

But apps are different, developers are, and so are the requirements and wishes, that developers have in order to include advertising in their apps. Additionally, it feels kind of strange, to use foreign librarys in your own code, without being able to actually have a look at the sources.

This is why madvertise decided to make all SDKs public as open source projects. We simply could not handle all the (we admit, pretty good) feature requests and suggestions that developers make. Well, we believe nobody can and that’s why we want to share the code with the whole community and enhanced it together. You can adapt the library much more quicker to whatever fits best for you.

Change Log