6.x Upgrade Guide: Android

Last Update:

This upgrade guide will help you update your games to use Chartboost Android SDKs v6.0+.

You'll also find stand-alone documentation for SDK 6.x here.


Key Changes

Below is an overview of the changes you need to be aware of in 6.x when upgrading from a previous (4.x) SDK version:

  • SDK initialization API and its required parameters have changed
  • All public methods are now static, so rather than using instance calls, you'll call the methods on the class object directly (e.g., you'd replace this.cb.showInterstitial(location); with Chartboost.showInterstitial(location); and omit any instance variable declarations (e.g., remove private Chartboost cb;)
  • Replace the sharedChartboost method inside onCreate(); (e.g., replace this.cb = Chartboost.sharedChartboost(); with the new initialization method, Chartboost.startWithAppId(this,appId,appSignature);)
  • ChartboostDelegate is not an interface anymore, rather it is an abstract class. This means you don't need to know (or implement) ahead of time the delegate callbacks that you need.
  • To create delegates, do not pass 'null' or a delegate object to this.cb.onCreate(...) anymore. It has its own class method, Chartboost.setDelegate(cb_delegate); which should be placed before Chartboost.onCreate(this); (details below).
  • Replace this.cb.onCreate(this, appId, appSignature, this.chartBoostDelegate); with Chartboost.onCreate(this);
  • Replace all instance variable calls with class method calls, e.g. this.cb.cacheInsterstitial() should become Chartboost.cacheInterstitial(location);
  • Method name changes on all has<CachedObject> methods to better clarify their meanings, e.g. hasCachedInterstitial, hasCachedVideo etc. are now hasInterstitial, hasRewardedVideo. These are static boolean methods that take a String location parameter and return true if cached content exists for the location.
  • New: Activity callbacks added: onPause() and onResume().
  • New: setAutoCacheAds(boolean autoCacheAds). Read below for more info.
  • There is no longer a CBPreferences, so please remove any instance calls for it: this.cbPref = CBPreferences.getInstance(); All impressions now use activities. Be sure to add the following entry in your AndroidManifest.xml file: 
    <activity android:name="com.chartboost.sdk.CBImpressionActivity"
                   android:excludeFromRecents="true"
                   android:hardwareAccelerated="true"
                   android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"
                   android:configChanges="keyboardHidden|orientation|screenSize" />
  • If used, the overriden public method for declaring whether interstitials are shown in a user's first session shouldRequestInterstitialsInFirstSession() needs to be replaced with the setter method Chartboost.setShouldRequestInterstitialsInFirstSession(boolean shouldRequest);
  • Optional (best practice): define appId and appSignature in /res/values/strings.xml, e.g.

    <string name="appId">5147872917ba476a7e000005</string>
    <string name="appSignature">50009149c7f545672c016b30f8b504ec2123d419</string>
    

    Then pass getResources().getString(R.string.appId) , getResources().getString(R.string.appSignature) instead of appId and appSignature as strings in the Chartboost.onCreate

 


Initialization Comparison

Below is an example of a 4.x initialization, compared to a 6.x initialization, for reference:

    /* Deprecated sample SDK initialization for Chartboost 4.x SDK */

    public class ChartboostSDKv4 extends Activity {
        private static final String TAG = "Chartboost";
        private Chartboost cb;
        private CBPreferences cbPrefs;

    @Override
    public void onCreate(Bundle savedInstanceState) { 
        super.onCreate(savedInstanceState);
        this.cb = Chartboost.sharedChartboost();
        this.cbPrefs = CBPreferences.getInstance();
        String appId = "";
        String appSignature = "";
        this.cb.onCreate(this, appId, appSignature, this.chartBoostDelegate);
        }
    }

    /* Sample SDK initialization for Chartboost 6.x SDK */
    public class ChartboostSDKv5 extends Activity {
        private static final String TAG = "Chartboost";

    @Override
    public void onCreate(Bundle savedInstanceState) { 
        super.onCreate(savedInstanceState);
        // Best practice: define your appId and appSignature constants in /res/values/strings.xml
        Chartboost.startWithAppId(this, getResources().getString(R.string.appId), getResources().getString(R.string.appSignature));
        Chartboost.setLoggingLevel(Level.ALL);
        Chartboost.setDelegate(cb_delegate);
        Chartboost.onCreate(this);
        }
    }

Steps

Follow these steps to upgrade your SDK to 6.x. After you've completed these steps, review the Key Changes again to ensure you've covered everything.

  1. Verify that your app still fits the minimum requirements:
    • Minimum API level 9 (Android OS 2.3)
    • Required permission: android.permission.INTERNET
    • Required permission: android.permission.ACCESS_NETWORK_STATE
    • Optional (recommended) permission: android.permission.WRITE_EXTERNAL_STORAGE
    • Optional (recommended) permission: android.permission.ACCESS_WIFI_STATE
    • Optional (recommended) permission: android.permission.READ_PHONE_STATE
  2. Remove any old chartboost.jar files from your project first.
    • If you don't have a libs directory in your project, create one and add the .jar file to it.
    • Optionally add chartboost.jar.properties and the doc directory to libs to get javadocs in your IDE.
  3. Verify the Google Play Services library is a dependency of your project.
    • The Google Play Services library has its own set of integration instructions, including additions to your Android Manifest and Proguard configuration.
    • You can follow the setup instructions outlined by Google at the Google Developer website
  4. Add the following entry in your AndroidManifest.xml file to display ads with smooth transitions and video playback:

    <activity android:name="com.chartboost.sdk.CBImpressionActivity"
                   android:excludeFromRecents="true"
                   android:hardwareAccelerated="true"
                   android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"
                   android:configChanges="keyboardHidden|orientation|screenSize" />
  5. Verify that the Chartboost SDK is imported into any activity that uses Chartboost:
  6. import com.chartboost.sdk.Libraries.CBLogging.Level;
    import com.chartboost.sdk.Model.CBError.CBClickError;
    import com.chartboost.sdk.Model.CBError.CBImpressionError;
    import com.chartboost.sdk.Tracking.CBAnalytics;
    import com.chartboost.sdk.CBLocation;
    import com.chartboost.sdk.CBImpressionActivity;
    import com.chartboost.sdk.Chartboost;
    import com.chartboost.sdk.ChartboostDelegate;
    
  7. If any activity in which you display Chartboost impressions can rotate between different orientations, you should add the following attribute to the activity in the AndroidManifest.xml file in order to achieve smooth video playback during orientation changes:

    android:configChanges="keyboardHidden|orientation|screenSize"
    
  8. Update the Chartboost SDK initialization in your launcher activity class so that the Chartboost callbacks and API calls can be made.
    There are two choices for initialization:

    • You can let the SDK handle this for you by simply extending ChartboostActivity. This removes the need for you to override any activity lifecycle methods such as onCreate, so you can simply call Chartboost.OnCreate(). SKIP TO STEP 11.
    • You can extend the application's main Activity explicitly (continue following steps 7 through 8). See example:

      public class <Your class name> extends Activity 
      
      @Override
      public void onCreate() {
          super.onCreate();
          Chartboost.startWithAppId(this, appId, appSignature);
          /* Optional: If you want to program responses to Chartboost events, supply a delegate object here and see step (10) for more information */
          //Chartboost.setDelegate( cb_delegate );
          Chartboost.onCreate(this);
          }   
      }
  9. Update your activity's onStart(), onPause(), onResume() ,onStop(), onDestroy(), and onBackPressed() methods with the following:

    @Override
    public void onStart() {
        super.onStart();
        Chartboost.onStart(this); 
    }
    
    
    @Override
    public void onResume() {
        super.onResume();
        Chartboost.onResume(this);
    }
    
    
    @Override
    public void onPause() {
        super.onPause();
        Chartboost.onPause(this);
    }
    
    
    @Override
    public void onStop() {
        super.onStop();
        Chartboost.onStop(this);
    }
    
    
    @Override
    public void onDestroy() {
        super.onDestroy();
        Chartboost.onDestroy(this);
    }
    
    
    @Override
    public void onBackPressed() {
        // If an interstitial is on screen, close it.
        if (Chartboost.onBackPressed())
            return;
        else
            super.onBackPressed();
    }
    
  10. Important: All your interstitial and video calls are static. You must pass in the location string to every call, null is no longer available. If you don't pass in the location, the SDK won't fetch any ads. You can use the CBLocation interface class to get a list of default location constants as well as define your own. Once a location is used, it will be added to your dashboard where you can customize settings for it.

    • Example Ad Calls:

      // Static and Video Interstitials
      Chartboost.cacheInterstitial(CBLocation.LOCATION_DEFAULT);
      Chartboost.showInterstitial(CBLocation.LOCATION_DEFAULT);
      
      
      // Rewarded Video
      Chartboost.showRewardedVideo(CBLocation.LOCATION_GAMEOVER);
      Chartboost.cacheRewardedVideo(CBLocation.LOCATION_GAMEOVER);
      
  11. Back in step (7) you may have noticed Chartboost.setDelegate(delegate). Note: we do not pass 'null' or a delegate object to an overridden onCreate() anymore to create delegates, since it has its own class method now. Call the method before calling Chartboost.onCreate(this) during initialization.

    • The parameter it takes is a delegate object, which allows you to respond to the events you are interested in by overriding the methods of your choice. Simply supply an object of the abstract class ChartboostDelegate as the parameter:

      private ChartboostDelegate cb_delegate = new ChartboostDelegate() {
      //Override the Chartboost delegate callbacks you wish to track and control
      }; 
      
    • This new method eliminates the need to extend from ChartboostDefaultDelegate as in previous versions of the SDK.

  12. You can choose to have your activities that use Chartboost extend from ChartboostActivity instead of Activity. Read more about this in our README.md. Important: If you use this integration method, you must initialize Chartboost with the method Chartboost.startWithAppId() before calling super.onCreate(). If you do not, an exception will be thrown, as the SDK needs to be initialized first before the SDK calls Chartboost.onCreate() internally. Example:

    public class <Your class name> extends ChartboostActivity {
        @Override
        public void onCreate() {
            Chartboost.startWithAppId(this, appId, appSignature);
            super.onCreate();
            fooBar();
        }
    }
    

Age Gate

If you were using the

didPauseClickForConfirmation()

method to handle Age Gate functionality, that method has now been updated to:

public void didPauseClickForConfirmation(Activity activity)

Dive deeper

Java API docs are provided along with SDK and a sample app.

Check out the code inside CBSample for examples.

If you plan on using Proguard, add the following to your proguard.cfg file (also make sure you follow Proguard instructions for the Google Play Services library):

 -keep class com.chartboost.** { *; }

Questions?

We want to your SDK integration be as smooth as possible, so that you can spend more of your time developing awesome games! If you encounter any issues, do not hesitate to contact our support team and we will be happy to help.