VRTCAL Android SDK Integration Guide -- SDK VERSION 1.0.2

Introduction


Thank you for your interest in the VRTCAL Android SDK.

Sign up for an account at https://vrtcal.com to download the SDK.

Technical Support


Need help? Please email us at support@vrtcal.com. You can also find helpful information at https://vrtcal.com

Table of Contents


Minimum Requirements


Our SDK is supported on Android 4.4 and above.

The minimum required permission is INTERNET, which is automatically added. Additional permissions are needed for optional features such as location services, third-party mediated ads, and MRAID ads. See their corresponding sections for more instructions.


Get Started


Download the SDK

Download our SDK from https://ui.vrtcal.com/sdk_downloads/VRTCALSDK_Android_1_0_2.zip and unzip the file. The resulting vrtcal-sdk directory will have the following files:

image alt text

Project Configuration

Add vrtcal-sdk.aar to your app

  1. Copy vrtcal-sdk.aar to your project’s libs directory <proj>/app/libs.

  2. Open <proj>/app/build.gradle and add the following line to the dependencies section:

     dependencies {
         [Other dependencies...]    
         implementation(name: 'vrtcal-sdk', ext: 'aar')
     }

    You might also need to add:

         repositories {
             flatDir {
                 dirs 'libs'
             }
         }
  3. Starting from Android 8, clear HTTP traffic is no longer allowed by default. However, some ads still use the non-secure HTTP protocol. To allow these ads to display properly, allow clear HTTP traffic by following instructions on Android Developer's page https://developer.android.com/training/articles/security-config.

    :
  4. For better ad targeting, we recommend that you do the following optional steps:

    • Include the following dependency in <proj>/app/build.gradle, so that ad personalization opt-out preference can be read:

        dependencies {
            [Other dependencies...]    
            implementation(name: 'vrtcal-sdk', ext: 'aar')
            implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
        }
        
    • Enable location updates by following instructions on Google Developers page https://developer.android.com/training/location. You can enable either FINE or COARSE location. You only need to include location libraries and add the permissions--your app does not need to request location updates, as our SDK will take care of that. For quick and simplified instructions, see Appendices: How to Enable Location Updates section.

  5. Import required classes in the Java class where you will be requesting ads, typically MainActivity.java:

     import com.vrtcal.sdk.*;

Initialize SDK

Before making ad requests you must initialize our SDK, as follows:

VrtcalSdk.init(context, appId, new VrtcalSdkListener() {
    @Override
    public void onSdkInitialized() {
        // SDK successfully initialized
    }

    @Override
    public void onSdkFailedToInitialize(Reason reason) {
        // SDK failed to initialize
    }
});

App ID can be obtained by adding an app in the SDK Management Section and following the instructions here. VrtcalSdkListener is the listener for SDK event callbacks. We recommend that you make this call as early as possible to avoid delays later in ad requests. A good place to call this is in your Activity's onCreate() function.


Showing Banner Ads



Create banner

Create a banner by instantiating a VrtcalBanner view:

VrtcalBanner banner = new VrtcalBanner(context);

You can also define your VrtcalBanner view in XML layout file and inflate it in your Activity.

Configure banner

You can listen to ad events by setting ad listener, as follows:

banner.setAdListener(new VrtcalBannerListener() {
    @Override
    public void onAdLoaded(VrtcalBanner banner) {
    }

    @Override
    public void onAdFailed(VrtcalBanner banner, Reason reason) {
    }

    @Override
    public void onAdClicked(VrtcalBanner banner) {
    }
});

When overriding ad listener methods, you only need to override the ones you are interested in. For onAdFailed() callback, the SDK provides a reason that could aid in debugging why an ad request failed.

Load banner and add banner to UI

Load and show the banner with the following call (the example assumes you already have a ViewGroup called bannerContainer):

banner.loadAd(adUnitId)
ViewGroup bannerContainer = findViewById(R.id.bannerContainer);
bannerContainer.addView(banner);

Ad Unit ID can be obtained by creating an Ad Unit in the SDK Management Section by following the instructions here, then you can use any Ad Unit ID in test mode for testing.


Destroy banner

When the banner is no longer needed, destroy it and remove it from UI:

((ViewGroup) findViewById(R.id.bannerContainer)).removeView(banner);
banner.destroy();
banner = null;

This will free up resources used by the banner.


Showing Interstitial Ads



Create interstitial

Create an interstitial by instantiating a VrtcalInterstitial object:

VrtcalInterstitial interstitial = new VrtcalInterstitial(context);

Configure interstitial

You can listen to ad events by setting ad listener, as follows:

interstitial.setAdListener(new VrtcalInterstitialListener() {
    @Override
    public void onAdLoaded(VrtcalInterstitial interstitial) {
    }

    @Override
    public void onAdFailedToLoad(VrtcalInterstitial interstitial, Reason reason) {
    }

    @Override
    public void onAdShown(VrtcalInterstitial interstitial) {
    }

    @Override
    public void onAdFailedToShow(VrtcalInterstitial interstitial, Reason reason) {
    }

    @Override
    public void onAdClicked(VrtcalInterstitial interstitial) {
    }

    @Override
    public void onAdDismissed(VrtcalInterstitial interstitial) {
    }
});

When overriding ad listener methods, you only need to override the ones you are interested in. We recommend that you listen to onAdLoaded() event to know when the ad is ready. For onAdFailedToLoad() callback, the SDK provides a reason that could aid in debugging why an ad request failed.

Load and show interstitial

Displaying an interstitial is a two-step operation: load, and show. Load the interstitial with the following call:

interstitial.loadAd(adUnitId);

Ad Unit ID can be obtained by creating an Ad Unit in the SDK Management Section by following the instructions here, then you can use any Ad Unit ID in test mode for testing.

Wait for SDK to call VrtcalInterstitialListener.onAdLoaded(), signifying that the ad is ready to be displayed. Then show the ad by calling:

interstitial.showAd();

Destroy interstitial

After an ad is shown and dismissed, the interstitial will destroy itself, so there is no need for the app to destroy it. However, if the app loads an interstitial ad and later decides not to show it, you should destroy it manually with the following:

interstitial.destroy();

This will free up all resources used by the interstitial.


Important Notes


SDK Event Callback Thread

All SDK, banner, and interstitial event callbacks are invoked from a background thread. If you perform a UI action in the callback function, e.g. adding a banner view to your UI, make sure to run it on the main thread.

Ad Lifecycle

You can only call loadAd() on VrtcalBanner or VrtcalInterstitial once for each instance. If you want to load another ad, you must create a new instance, and in the case of banners, you must remove the old VrtcalBanner from UI and replace it with the new one. This, however, does not apply if you use our SDK's banner refresh mechanism. See Banner Refresh section below.

Once destroy() is called, the ad object will no longer load ads or receive events callbacks, so make sure to call destroy() only after you are sure you will no longer use it.

You can let our SDK take care of banner refresh by setting a refresh interval on the Edit Ad Unit page on our website. If you use this mechanism, our SDK will reload banner ads in the same VrtcalBanner view object, so you can just leave the view in the UI.

Keep in mind that VrtcalBannerListener.onAdLoaded() callback is invoked every time the banner refreshes successfully, so be careful not to add any code that should be not repeated. Similarly, VrtcalListener.onAdFailedToLoad() is called on every failed refresh. Our SDK will attempt again in the next refresh interval if the reason for failure is one of the following: no fill, request timeout, request throttled, or server communication error (e.g. temporarily losing the network connection). To stop banner refresh, call destroy() on the banner view.


ProGuard


For core features, the required rules are already included in our vrtcal-sdk.aar file. However, additional steps are needed if you use GDPR or if you intend to display third-party mediated ads. See their respective sections for more instructions.


GDPR


We support IAB's GDPR framework. Follow IAB's instructions on how to save the user's GDPR settings in Android's SharedPreferences and/or to integrate their SDK in your project. You should set GDPR settings before you invoke any VRTCAL SDK API functionality.


MRAID


Our SDK can display MRAID 3.0 ads. The permissions needed to support all MRAID features are listed below, some of which require the app to prompt the user for consent. All permissions are optional, but keep in mind that any permission that is omitted will prevent the corresponding features from working.

WRITE_EXTERNAL_STORAGE
READ_CALENDAR
WRITE_CALENDAR
SEND_SMS
CALL_PHONE

MRAID ads have the ability to expand and occupy the entire screen. When the ad expands to full screen or returns to its original size, the SDK notifies the app via banner event callbacks. The app can then take the appropriate action, e.g. pause an on-going game. These callbacks are part of the VrtcalBannerListener listener:

banner.setAdListener(new VrtcalBannerListener() {
    @Override
    public void onAdLoaded(VrtcalBanner banner) {
    }

    @Override
    public void onAdFailed(VrtcalBanner banner, Reason reason) {
    }

    @Override
    public void onAdClicked(VrtcalBanner banner) {
    }

    @Override
    public void onAdExpanded(VrtcalBanner banner) {
    }

    @Override
    public void onAdCollapsed(VrtcalBanner banner) {
    }
});

Ad Mediation (VRTCAL to MoPub)


If your app is integrated with VRTCAL SDK, and you want the ability to serve MoPub ads through our SDK, follow these instructions:

  1. Supported version: Our latest SDK is tested with MoPub 5.4.0 SDK and should work with previous minor releases as well. If you are using a version of MoPub SDK that is not compatible, contact support@vrtcal.com for a possible custom adapter.

  2. Integrate VRTCAL SDK: If you have not done so, follow instructions in this document to integrate our SDK with your project. To isolate issues, we recommend that you first test the integration by displaying one of our test ads.

  3. Integrate MoPub SDK: Set up your project following instructions provided by MoPub. You only need to do the steps listed below. You should not do the code integration.

    • Step 1. Download the MoPub Android SDK

    • Step 2. Add the MoPub SDK to Your Project

    • Step 3. Update Your Android Manifest

    • Step 4. Add a Network Security Configuration File

    • Step 5. Optionally Use ProGuard

  4. Ad unit and line item configuration:

    • If you have not done so already, create the MoPub ad units from MoPub's website

    • Add you Mopub ad unit to the VRTCAL UI by going to the "manage line items" section of the ad unit you wish to add it to. Make sure to choose "NETWORK-Mopub" as the Partner/Line Item Type. See the VRTCAL UI reference guide here for additional details: SDK UI Doc

  5. Add custom event to your project

    • Create the folder com/vrtcal/sdk/customevent in your project's source folder, i.e. <proj>/app/src/main/java/com/vrtcal/sdk/customevent.

    • When you downloaded and unzipped our SDK, there is a vrtcal-sdk folder. Go into vrtcal-sdk/mediation/MoPub folder.

    • Copy MoPubCustomEvent.java to the com/vrtcal/sdk/customevent folder in your project.

The VRTCAL ad unit should now serve MoPub ads (depending on your ad unit configuration you might not always see MoPub ads).


Ad Mediation (MoPub to VRTCAL)


If your app is integrated with MoPub SDK, but you want to serve VRTCAL ads through their SDK, follow these instructions:

  1. Supported version: Our latest SDK is tested with MoPub 5.4.0 SDK and should work with previous minor releases as well. If you are using a version of MoPub SDK that is not compatible, contact support@vrtcal.com for a possible custom adapter.

  2. Integrate MoPub SDK: Follow MoPub's instructions on how to integrate their SDK into your project, including the code integration instructions.

  3. Integrate VRTCAL SDK: If you have not done so, follow instructions in this document to integrate our SDK with your project. You only need to do the steps listed below. You should not do the code integration.

    1. Download the SDK

    2. Project Configuration

    3. ProGuard (if applicable)

    4. GDPR (if applicable)

    5. MRAID (if applicable)

  4. Ad unit and line item configuration:

    • If you have not done so already, create your VRTCAL Ad Unit via the SDK Management Section and follow the instructions here to get the App ID and the newly created Ad Unit ID.

    • Go to MoPub's website and create your ad unit and line item. When creating line item, enter the following values:

      • For Network, select Custom SDK Network from drop-down list

      • For Custom event class, enter:

        For banners:
        com.vrtcal.sdk.customevent.MoPubVrtcalCustomEventBanner

        For interstitials:
        com.vrtcal.sdk.customevent.MoPubVrtcalCustomEventInterstitial
      • For Custom event data, enter:

          {"appId":"app_id","zoneId":"zone_id"}

        Where app_id and ad_unit_id are your App ID and Ad Unit ID, respectively. E.g.:

          {"appId":"11073","zoneId":"10005"}
  5. Add custom event to your project

    • Create the folder com/vrtcal/sdk/customevent in your project's source folder, i.e. <proj>/app/src/main/java/com/vrtcal/sdk/customevent.

    • When you downloaded and unzipped our SDK, there is a vrtcal-sdk folder. Go into vrtcal-sdk/mediation/MoPub folder.

    • Copy the following files to the com/vrtcal/sdk/customevent folder in your project:

      MoPubVrtcalCustomEventBanner.java

      MoPubVrtcalCustomEventInterstitial.java

      MoPubVrtcalCustomEventUtil.java

The MoPub ad unit should now serve VRTCAL ads (depending on your ad unit configuration you might not always see VRTCAL ads).


Sample App


To run the sample app, open VrtcalSampleApp from Android Studio, and go to Run → Run ‘app’ from menu to deploy the app to your device. You should see this:

image alt text

Click on Load Banner to load a banner, and Destroy Banner to remove it. For interstitials, click on either Load Interstitial, and when "Interstitial loaded" toast appears, click on Show Interstitial.


Appendices


How to Enable Location Updates

Here is a simplified set of instructions on how to enable location updates. Please consult Android Developers pages for full instructions.

  1. Add location dependency in build.gradle:

     dependencies {
         [Other dependencies...]    
         implementation 'com.google.android.gms:play-services-location:17.0.0'
     }
  2. Add location permission to AndroidManifest.xml:

     <manifest>
         <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
     </manifest>
  3. Request permission (this is from Android Developer page, with minor changes for our needs):

     if (ContextCompat.checkSelfPermission(activity, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
         // Permission is not granted
         // Should we show an explanation?
         if (ActivityCompat.shouldShowRequestPermissionRationale(activity,
                 Manifest.permission.ACCESS_FINE_LOCATION)) {
             // Show an explanation to the user *asynchronously* -- don't block
             // this thread waiting for the user's response! After the user
             // sees the explanation, try again to request the permission.
         } else {
             // No explanation needed; request the permission
             ActivityCompat.requestPermissions(activity,
                     new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
                     MY_PERMISSIONS_REQUEST_READ_CONTACTS);
             // MY_PERMISSIONS_REQUEST_READ_CONTACTS is an
             // app-defined int constant. The callback method gets the
             // result of the request.
         }
     } else {
         // Permission has already been granted
     }

FAQ


Q: Where can I reach out for help?

A: Reach out to us at support@vrtcal.com

Q: How do I increase the likelihood that my ad gets filled?

A: There are many factors that affect advertiser interest and spend. Aside from the content type/category of your application, there things that you can do to build and maintain advertiser interest, such as (1) if you are able to include location data; (2) set a refresh rate of 30 seconds or greater; (3) include as much device data that is available; and (4) make sure the ad unit location is a good placement with content.

Q: Why are some ads showing up as blank?

A: This could be for many reasons, it may be an ad that was configured incorrectly by the advertiser, it could be that the ad is using the non-secure HTTP protocol which requires extra configuration to allow ads that use HTTP.

Q: Does VRTCAL have custom events for other SDKs besides MoPub?

A: The current SDK only includes a custom event for MoPub at the moment, but we have others on the way.

Q: Where do I create an Ad Unit?

A: Once you are a registered user on vrtcal.com create your VRTCAL Ad Unit via the SDK Management Section and follow the instructions here.

Last updated on 4th March 2020