Yieldmo Android SDK 2.2 Documentation
Yieldmo Android SDK 2.2 Documentation Last Updated: 8/25/2015 1. Overview 2. Before you begin 3. Getting Started: Integrating the SDK a. Requirements b. Yieldmo SDK Integration Android Studio c. Yieldmo SDK Integration Eclipse 4. Yieldmo Ad Integration Native a. Simple Views b. ListViews and TableViews 5. Updating the Yieldmo SDK 6. Configuring User Permissions 7. Tips & Tricks
1. Overview Yieldmo’s Android SDK 2.2 simplifies the integration process and adds support for our animated, high CPM in-content formats. Your Publisher Operations lead can enable your placements to serve any of the following ad formats in your app: Window
Pull
Hyperscroller
Domino
Postcard
Ticker
Store
You do not need to select a specific format for your placements. Yieldmo’s ad servers will automatically serve the best performing ad format for each impression, maximizing the monetization potential of your implementation. If, however, you’d like to limit the formats that are allowed to display, your Publisher Operations lead can accommodate this. The Android SDK allows you to insert Yieldmo ads into any Android native view. If you have any questions or concerns, please contact our product team at [email protected] .
2. Before you begin The Android SDK files are provided by your Yieldmo publisher operations lead. The distribution includes a demo app Android Studio project, and the SDK library package as ymsdk.aar (for Android Studio) and ymsdk.jar (for Eclipse). Make sure you have received the following from your Yieldmo publisher operations lead before you start integrating the SDK: ● Your publisher app ID. For testing only use 10b289f8‐df7d‐11e3‐a6a3‐82687f4fc17c, which can be found in the SDK as YMConstants.testAppId. ● Your placement IDs for the app (e.g. 1234567) . If you already have placement IDs for your mobile website, the native app IDs will be different. ● Testing Placement ID’s. For testing only , you may use the following placements IDs, which can also be found in the SDK in YMConstants: ○ Store: 4 ads 1017402353938447105 ○
Postcard 1017319088019847539
○
Ticker 1077439248806033842
○
Domino 1077440568225020344
○
Hyperscroller 1123689821356014225
○
Window 1135308480138558232
○
Pull 1135307678690949910
Your publisher app ID and placement IDs will be provided by the Yieldmo Publisher Operations team.
3. Getting Started: Integrating the SDK a. Requirements
●
Android Studio version 1.1.0 or newer or Eclipse Indigo (Version 3.7.2) or newer
● ● ●
Your app must target Android API level 15 or higher ( minSdkVersion) Your app must link with Google Play Services version 7.5.75 or higher Use Android Build Tools version 22.0.1 or higher
b. Yieldmo SDK Integration ‐ Android Studio The library for Android Studio is distributed as an Android archive (.aar) file. Follow these steps to add the library to your app. 1. Set up your app to link with the Google Play Services library by following these instructions: https://developer.android.com/google/playservices/setup.html . a. The only Google Play service API that needs to be integrated into your application is Google Mobile Ads. Scroll down to the “Selecting compiling APIs into your executable” section, and find the corresponding “Description in build.gradle” for Google Mobile Ads (ex. “com.google.android.gms:playservicesads:7.8.0” ). If you integrate the first build.gradle description, you will be integrating ALL Google Play Services. 2. Create a directory called libs in your project directory on the same level as your app’s src directory and copy ymsdk.aar to it. 3. In the build.gradle file of your app’s project module (not the toplevel build.gradle file) add the following line in the dependencies section: 1 compile (' com.yieldmo.sdk:ymsdk:2.2@aar') {t ransitive= t rue }
4. Add the following section to the same build.gradle file below the dependencies section: 1 repositories { f latDir { dirs ' libs'} }
5. Verify that minSDKVersion is set to 15 or higher in the android section. After completing these steps, your app project’s build.gradle file should look similar to this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
// build.gradle apply p lugin: ' com.android.application' android { compileSdkVersion 2 2 buildToolsVersion ‘ 22.0.1’ defaultConfig { applicationId " com.yieldmo.demo" minSdkVersion 1 5 targetSdkVersion 2 2 versionCode 1 versionName ‘1.0’ } } dependencies { compile 'com.google.android.gms:play‐services:6.5.87' compile (' com.yieldmo.sdk:ymsdk:2.2@aar') {t ransitive= t rue } } repositories { flatDir { dirs 'libs’ }}
6. Add the following code to the onCreate() method of your Application class to initialize the library: 1 2 3 4 5 6 7 8
import c om.yieldmo.sdk.YMSdk; public c lass M yApp e xtends A pplication { @ Override p ublic v oid onCreate( ) { super. o nCreate (); YMSdk. init( g etApplicationContext( ), " your_ym_app_id" , f alse) ; } }
c. Yieldmo SDK Integration ‐ Eclipse The library for Eclipse is distributed as a Java archive (.jar) file. Follow these steps to add the library to your app: 1. Set up your app to link with the Google Play Services library by following these instructions: https://developer.android.com/google/playservices/setup.html 2. Create a directory called libs in your project directory on the same level as your app’s src directory and copy ymsdk.jar to it. 3. Create a directory called assets in your project directory on the same level as the libs directory. Create a directory called fonts in the assets directory. Copy fontello.ttf from the SDK distribution files to this directory.
4. Open your app’s AndroidManifest.xml and verify that minSDKVersion is set to 15 or higher in the android section. 5. Verify that the following permissions are included in your AndroidManifest.xml file: 1 <uses‐permission a ndroid:name=" android.permission.INTERNET" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_NETWORK_STATE" / >
To allow the SDK to use location information for ad targeting, add at least one following permissions to your AndroidManifest.xml file: 1 <uses‐permission a ndroid:name=" android.permission.ACCESS_FINE_LOCATION" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_COARSE_LOCATION" / >
6. Import the YMSdk into your application source file and add the following code to the onCreate() method to initialize the library: 1 2 3 4 5 6 7 8
import c om.yieldmo.sdk.YMSdk public c lass M yApp e xtends Application { @ Override p ublic v oid onCreate( ) { super. o nCreate (); YMSdk. init( g etApplicationContext( ), " your_ym_app_id" ); } }
If your application does not use a custom Application object then you should initialize the YM library in the onCreate() method of the app’s activities that you’d like to display Yieldmo ads: 1 2 3 4 5 6 7
public c lass M yActivity e xtends Activity { @Override p rotected v oid onCreate( B undle savedInstanceState) { s uper. o nCreate (s avedInstanceState) ; setContentView (R . l ayout. a ctivity_my) ; Y MSdk. init( g etApplicationContext( ), " your_ym_app_id" ); }
4. Yieldmo Ad Integration You can add YM ads to your app using XML layout files or programmatically.
a. Adding YM Ads using layout files Add a YMView to any ViewGroup in your activity’s XML layout file using the following XML syntax:
● ● ●
Replace placement‐id with your assigned YM placement ID Use any unique ID for android:id, a required view attribute. Do not change the android:layout_width and android:layout_height attribute values. You can add a YMView to any ViewGroup in your view hierarchy.
● b. Adding YM Ads Programmatically Add this code to your activity’s onCreate() method implementation: 1 2 3 4 5
// Get the activity root view group ViewGroup rootView = (ViewGroup) f indViewById (R.i d. r ootView ); // add a YM ad anywhere in your view hierarchy rootView.a ddView( n ew YMView( this , " placement‐id") );
Threading Considerations You must call all YM SDK methods from your app’s main UI thread and not from a background thread. All SDK callbacks in your code will be called by the SDK on your app’s main UI thread.
5. Updating the Yieldmo SDK When updating the Yieldmo SDK to the latest version, replace the existing ymsdk.aar or ymsdk.jar files in the libs directory of your app with the updated SDK version distribution.
6. Configuring User Permissions By default, Android Studio automatically merges the following SDK permission requests into your app’s main AndroidManifest.xml file:
1 <uses‐permission a ndroid:name=" android.permission.INTERNET" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_NETWORK_STATE" / >
The above permissions are required for the Yieldmo SDK to serve ads. To take advantage of locationtargeted ads, we recommend you add one or more of the additional location permissions below to your app’s manifest file. 1 <uses‐permission a ndroid:name=" android.permission.ACCESS_FINE_LOCATION" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_COARSE_LOCATION" / >
If your app already asks for either of these permissions, the Yieldmo SDK can serve locationtargeted ads without further action on your part. You can also add the following permission to enable phone call ads. 1 <uses‐permission a ndroid:name=" android.permission.CALL_PHONE" / >
7. Tips & Tricks Running the Demo Apps This SDK includes a fully functional demo app that you can use to get started quickly. Follow these instructions to build and run the demo app in Android Studio or in Eclipse. Android Studio Demo App 1. Open Android Studio 2. Choose the Import Project command from the file menu 3. Select the DemoApp folder in the sdk folder in the dialog box 4. Run the demo app in the emulator or on a USBattached Android mobile device 5. To access additional demos, tap the menu button on the rightside of the demo app’s action bar at the top of the screen Eclipse Demo App 1. Open Eclipse (Juno or later) 2. Import the Eclipse demo app to your workspace 3. Run the demo app in the emulator or on a USBattached Android mobile device
4. To access additional demos, tap the menu button on the rightside of the demo app’s action bar at the top of the screen Adapter View Usage Optimization Store a reference for each YMView you have created for a placement ID and return it in getView() to avoid creating a new object on every request to display a YM ad. Refer to the SDK demo app code. Optional Callbacks To create callbacks that will be fired when an ad is displayed or when an error occurs during display, implement YMViewDelegate and pass the implementation to YMView’ s constructor or use YMView.setDelegate(). The callback code will be run in the main UI thread. 1 2 3 4 5 6 7 8 9
YMView ymView = new YMView( getContext( ), placementId, n ew YMViewDelegate() { @ Override p ublic v oid adDisplayFailed(YMView ymView, YMException exception) { // exception handling goes here } @ Override p ublic v oid adDisplayed(YMView ymView) { // code to execute on success goes here } });
1. Overview Yieldmo’s Android SDK 2.2 simplifies the integration process and adds support for our animated, high CPM in-content formats. Your Publisher Operations lead can enable your placements to serve any of the following ad formats in your app: Window
Pull
Hyperscroller
Domino
Postcard
Ticker
Store
You do not need to select a specific format for your placements. Yieldmo’s ad servers will automatically serve the best performing ad format for each impression, maximizing the monetization potential of your implementation. If, however, you’d like to limit the formats that are allowed to display, your Publisher Operations lead can accommodate this. The Android SDK allows you to insert Yieldmo ads into any Android native view. If you have any questions or concerns, please contact our product team at [email protected] .
2. Before you begin The Android SDK files are provided by your Yieldmo publisher operations lead. The distribution includes a demo app Android Studio project, and the SDK library package as ymsdk.aar (for Android Studio) and ymsdk.jar (for Eclipse). Make sure you have received the following from your Yieldmo publisher operations lead before you start integrating the SDK: ● Your publisher app ID. For testing only use 10b289f8‐df7d‐11e3‐a6a3‐82687f4fc17c, which can be found in the SDK as YMConstants.testAppId. ● Your placement IDs for the app (e.g. 1234567) . If you already have placement IDs for your mobile website, the native app IDs will be different. ● Testing Placement ID’s. For testing only , you may use the following placements IDs, which can also be found in the SDK in YMConstants: ○ Store: 4 ads 1017402353938447105 ○
Postcard 1017319088019847539
○
Ticker 1077439248806033842
○
Domino 1077440568225020344
○
Hyperscroller 1123689821356014225
○
Window 1135308480138558232
○
Pull 1135307678690949910
Your publisher app ID and placement IDs will be provided by the Yieldmo Publisher Operations team.
3. Getting Started: Integrating the SDK a. Requirements
●
Android Studio version 1.1.0 or newer or Eclipse Indigo (Version 3.7.2) or newer
● ● ●
Your app must target Android API level 15 or higher ( minSdkVersion) Your app must link with Google Play Services version 7.5.75 or higher Use Android Build Tools version 22.0.1 or higher
b. Yieldmo SDK Integration ‐ Android Studio The library for Android Studio is distributed as an Android archive (.aar) file. Follow these steps to add the library to your app. 1. Set up your app to link with the Google Play Services library by following these instructions: https://developer.android.com/google/playservices/setup.html . a. The only Google Play service API that needs to be integrated into your application is Google Mobile Ads. Scroll down to the “Selecting compiling APIs into your executable” section, and find the corresponding “Description in build.gradle” for Google Mobile Ads (ex. “com.google.android.gms:playservicesads:7.8.0” ). If you integrate the first build.gradle description, you will be integrating ALL Google Play Services. 2. Create a directory called libs in your project directory on the same level as your app’s src directory and copy ymsdk.aar to it. 3. In the build.gradle file of your app’s project module (not the toplevel build.gradle file) add the following line in the dependencies section: 1 compile (' com.yieldmo.sdk:ymsdk:2.2@aar') {t ransitive= t rue }
4. Add the following section to the same build.gradle file below the dependencies section: 1 repositories { f latDir { dirs ' libs'} }
5. Verify that minSDKVersion is set to 15 or higher in the android section. After completing these steps, your app project’s build.gradle file should look similar to this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
// build.gradle apply p lugin: ' com.android.application' android { compileSdkVersion 2 2 buildToolsVersion ‘ 22.0.1’ defaultConfig { applicationId " com.yieldmo.demo" minSdkVersion 1 5 targetSdkVersion 2 2 versionCode 1 versionName ‘1.0’ } } dependencies { compile 'com.google.android.gms:play‐services:6.5.87' compile (' com.yieldmo.sdk:ymsdk:2.2@aar') {t ransitive= t rue } } repositories { flatDir { dirs 'libs’ }}
6. Add the following code to the onCreate() method of your Application class to initialize the library: 1 2 3 4 5 6 7 8
import c om.yieldmo.sdk.YMSdk; public c lass M yApp e xtends A pplication { @ Override p ublic v oid onCreate( ) { super. o nCreate (); YMSdk. init( g etApplicationContext( ), " your_ym_app_id" , f alse) ; } }
c. Yieldmo SDK Integration ‐ Eclipse The library for Eclipse is distributed as a Java archive (.jar) file. Follow these steps to add the library to your app: 1. Set up your app to link with the Google Play Services library by following these instructions: https://developer.android.com/google/playservices/setup.html 2. Create a directory called libs in your project directory on the same level as your app’s src directory and copy ymsdk.jar to it. 3. Create a directory called assets in your project directory on the same level as the libs directory. Create a directory called fonts in the assets directory. Copy fontello.ttf from the SDK distribution files to this directory.
4. Open your app’s AndroidManifest.xml and verify that minSDKVersion is set to 15 or higher in the android section. 5. Verify that the following permissions are included in your AndroidManifest.xml file: 1 <uses‐permission a ndroid:name=" android.permission.INTERNET" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_NETWORK_STATE" / >
To allow the SDK to use location information for ad targeting, add at least one following permissions to your AndroidManifest.xml file: 1 <uses‐permission a ndroid:name=" android.permission.ACCESS_FINE_LOCATION" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_COARSE_LOCATION" / >
6. Import the YMSdk into your application source file and add the following code to the onCreate() method to initialize the library: 1 2 3 4 5 6 7 8
import c om.yieldmo.sdk.YMSdk public c lass M yApp e xtends Application { @ Override p ublic v oid onCreate( ) { super. o nCreate (); YMSdk. init( g etApplicationContext( ), " your_ym_app_id" ); } }
If your application does not use a custom Application object then you should initialize the YM library in the onCreate() method of the app’s activities that you’d like to display Yieldmo ads: 1 2 3 4 5 6 7
public c lass M yActivity e xtends Activity { @Override p rotected v oid onCreate( B undle savedInstanceState) { s uper. o nCreate (s avedInstanceState) ; setContentView (R . l ayout. a ctivity_my) ; Y MSdk. init( g etApplicationContext( ), " your_ym_app_id" ); }
4. Yieldmo Ad Integration You can add YM ads to your app using XML layout files or programmatically.
a. Adding YM Ads using layout files Add a YMView to any ViewGroup in your activity’s XML layout file using the following XML syntax:
● ● ●
Replace placement‐id with your assigned YM placement ID Use any unique ID for android:id, a required view attribute. Do not change the android:layout_width and android:layout_height attribute values. You can add a YMView to any ViewGroup in your view hierarchy.
● b. Adding YM Ads Programmatically Add this code to your activity’s onCreate() method implementation: 1 2 3 4 5
// Get the activity root view group ViewGroup rootView = (ViewGroup) f indViewById (R.i d. r ootView ); // add a YM ad anywhere in your view hierarchy rootView.a ddView( n ew YMView( this , " placement‐id") );
Threading Considerations You must call all YM SDK methods from your app’s main UI thread and not from a background thread. All SDK callbacks in your code will be called by the SDK on your app’s main UI thread.
5. Updating the Yieldmo SDK When updating the Yieldmo SDK to the latest version, replace the existing ymsdk.aar or ymsdk.jar files in the libs directory of your app with the updated SDK version distribution.
6. Configuring User Permissions By default, Android Studio automatically merges the following SDK permission requests into your app’s main AndroidManifest.xml file:
1 <uses‐permission a ndroid:name=" android.permission.INTERNET" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_NETWORK_STATE" / >
The above permissions are required for the Yieldmo SDK to serve ads. To take advantage of locationtargeted ads, we recommend you add one or more of the additional location permissions below to your app’s manifest file. 1 <uses‐permission a ndroid:name=" android.permission.ACCESS_FINE_LOCATION" / > 2 <uses‐permission a ndroid:name=" android.permission.ACCESS_COARSE_LOCATION" / >
If your app already asks for either of these permissions, the Yieldmo SDK can serve locationtargeted ads without further action on your part. You can also add the following permission to enable phone call ads. 1 <uses‐permission a ndroid:name=" android.permission.CALL_PHONE" / >
7. Tips & Tricks Running the Demo Apps This SDK includes a fully functional demo app that you can use to get started quickly. Follow these instructions to build and run the demo app in Android Studio or in Eclipse. Android Studio Demo App 1. Open Android Studio 2. Choose the Import Project command from the file menu 3. Select the DemoApp folder in the sdk folder in the dialog box 4. Run the demo app in the emulator or on a USBattached Android mobile device 5. To access additional demos, tap the menu button on the rightside of the demo app’s action bar at the top of the screen Eclipse Demo App 1. Open Eclipse (Juno or later) 2. Import the Eclipse demo app to your workspace 3. Run the demo app in the emulator or on a USBattached Android mobile device
4. To access additional demos, tap the menu button on the rightside of the demo app’s action bar at the top of the screen Adapter View Usage Optimization Store a reference for each YMView you have created for a placement ID and return it in getView() to avoid creating a new object on every request to display a YM ad. Refer to the SDK demo app code. Optional Callbacks To create callbacks that will be fired when an ad is displayed or when an error occurs during display, implement YMViewDelegate and pass the implementation to YMView’ s constructor or use YMView.setDelegate(). The callback code will be run in the main UI thread. 1 2 3 4 5 6 7 8 9
YMView ymView = new YMView( getContext( ), placementId, n ew YMViewDelegate() { @ Override p ublic v oid adDisplayFailed(YMView ymView, YMException exception) { // exception handling goes here } @ Override p ublic v oid adDisplayed(YMView ymView) { // code to execute on success goes here } });
