Vrtcal Android SDK Integration Guide

Table of Contents

• Minimum Requirements
• Downloading SDK
• Project Configuration
• Initialize SDK
• Showing Banner Ads
  • Create banner
  • Configure banner
  • Load and show banner
  • Add banner view to UI
  • Destroy banner
• Showing Interstitial Ads
  • Create interstitial
  • Configure interstitial
  • Load and show interstitial
  • Destroy interstitial
• Important Notes
  • SDK Event Callback Thread
  • Ad Lifecycle
  • Banner Refresh
• ProGuard
• GDPR
  • IAB GDPR framework
  • VRTCAL GDPR framework
• MRAID
• Ad Mediation (VRTCAL to MoPub)
• Ad Mediation (MoPub to VRTCAL)
• Sample App
• Appendices
  • How to Enable Location Update

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.

Downloading SDK

Download our SDK from https://drive.google.com/open?id=1I5FZLYbwc-FpPoBH3GPaaLFBvyd9HnLf [insert actual URL] and unzip the file. The resulting vrtcal-sdk directory will have the following files:

VrtcalSampleApp
mediation
vrtcal-sdk.aar

Project Configuration

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

2. Open /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 /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 update 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 Update 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(ErrorCode errorCode) {

        // SDK failed to initialize

    }

});

App ID can be obtained from your account manager, or you can use 11073 for testing [replace with actual test app ID]. 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,

            ErrorCode errorCode) {

    }

    @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 an error code that could aid in debugging why an ad request failed.

Load and show banner

Load and show the banner with the following call:

banner.loadAd(zoneId);

Zone ID can be obtained from your account manager, or you can use 10005 for testing [replace with actual test zone ID].

Add banner view to UI

You can add the VrtcalBanner view to UI any time after it is created. What follows is an example of adding the view after SDK calls the onAdLoaded() callback (the example assumes you already have a ViewGroup called bannerContainer):

banner.setAdListener(new VrtcalBannerListener() {
    @Override

    public void onAdLoaded(final VrtcalBanner banner) {

        runOnUiThread(new Runnable() {

            @Override

            public void run() {

                ViewGroup bannerContainer = findViewById(R.id.bannerContainer);
                if (bannerContainer.indexOfChild(banner) == -1) {
                    bannerContainer.addView(banner);
                }
            }
        });
    }
});

In example above notice that:

• All SDK event callbacks are invoked from background thread, and since adding views is a UI operation, it needs to run on main thread.

• If banner refresh is enabled, the onAdLoaded() will be called on every successfully banner refresh. Therefore before we add the banner view we need to verify that it has not already been added.

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 an 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,
        ErrorCode errorCode) {
    }

    @Override
    public void onAdShown(VrtcalInterstitial interstitial) {
    }

    @Override
    public void onAdFailedToShow(VrtcalInterstitial interstitial,
        ErrorCode errorCode) {
    }

    @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 an error code 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(zoneId);

Zone ID can be obtained from your account manager, or you can use 10009 for testing [replace with actual test zone ID].

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 background thread. If you perform UI action in the callback function, e.g. adding banner view to your UI, make sure to run it on 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.

Banner Refresh

You can let our SDK take care of banner refresh by setting a refresh interval on 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 banner refreshes successfully, so if you are adding VrtcalBanner view to your UI in that callback, you must add a check to make sure you do not add the same view to UI twice. Similarly, VrtcalListener.onAdFailedToLoad() is called on every failed refresh, but our SDK will attempt again in next release interval if the reason for failure is one of the following: no fill, request timeout, request throttled, and server communication error (e.g. temporary losing 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 provide two mechanisms to set GDPR settings: IAB's GDPR framework, and our VRTCAL method. Instructions on how to use each method is provided below. If you set GDPR values with both IAB framework and VRTCAL mechanism, then the IAB provider's values will take precedence.

IAB GDPR framework

Follow instructions in IAB's GDPR documentation. You will be guided to include their SDK in your project, and to save user settings in Android's SharedPreferences. If you use ProGuard, you must keep the names of IAB SDK library classes by adding the following to your rules:

-keep class com.iab.gdpr.** { *; }

VRTCAL GDPR framework

If you prefer to use VRTCAL's mechanism, the APIs are:

VrtcalSdk.setSubjectToGdpr(Boolean subjectToGdpr)
VrtcalSdk.setGdprConsent(String gdprConsent)

The setSubjectToGdpr() API specifies whether GDPR laws apply to current user. If you do not set the value, or if you set it to null, it is interpreted as "not subject to GDPR". The setGdprConsent() API sets the user consent value. The gdprConsent parameter is expected to be "0" or "1". Any value except "1" is interpreted as "no consent".

The above methods should be called before you invoke any SDK API.

MRAID

Our SDK can display MRAID 3.0 ads. The permissions needed to support all features MRAID 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,
        ErrorCode errorCode) {
    }

    @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

   • Ask your VRTCAL account manager to configure VRTCAL ad units and line items to mediate to MoPub ad units you created in previous step. You will need to give your account manager the MoPub ad unit ID.

5. Add custom event to your project

   • Create the folder com/vrtcal/sdk/customevent in your project's source folder, i.e. /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. Downloading 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, ask your VRTCAL account manager to create your VRTCAL ad unit. Ask for integration parameters, and write down 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:

         com.vrtcal.sdk.customevent.MoPubVrtcalCustomEventBanner for banners, or
         com.vrtcal.sdk.customevent.MoPubVrtcalCustomEventInterstitial for interstitials

     • For Custom event data, enter:

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

       Where app_id and zone_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. /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:

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 Update

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 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
    }