Introduction

Thank you for your interest in the VRTCAL Android SDK.

Sign up for an account to monetize with Vrtcal.

Technical Support

Need help? Please email us at support@vrtcal.com.

You can also find helpful information at https://www.vrtcal.com

Table of Contents

• Minimum Requirements
• Get Started
  • Download the SDK
  • Project Configuration
  • Initialize SDK
  • Setting UnifID (Optional)
• Showing Banner Ads
• Showing Interstitial Ads
• Showing Digital Audio (DAAST) Ads
• Native Ads
• Important Notes
  • SDK Event Callback Thread
  • Ad Lifecycle
  • Banner Refresh
• ProGuard
• GDPR
• MRAID
• Ad Mediation (VRTCAL to Google SDKs [AdMob/GAM])
• Ad Mediation (Google SDKs [AdMob/GAM] to VRTCAL)
• Ad Mediation (VRTCAL to IronSource)
• Ad Mediation (IronSource to VRTCAL)
• Ad Mediation (VRTCAL to AppLovin)
• Ad Mediation (AppLovin to VRTCAL)
• Ad Mediation (VRTCAL to Fyber-FairBid)
• Ad Mediation (VRTCAL to Fyber-Marketplace)
• Ad Mediation (VRTCAL to Smaato)
• Ad Mediation (VRTCAL to Tapjoy)
• Ad Mediation (VRTCAL to Vungle)
• Sample App
• Appendices
• How to Enable Location Update
• FAQ

Minimum Requirements

SDK Size: 150K
Average Memory Footprint: <10MB

Our SDK is supported on API Level 19 (Android 4.4) and above.

The minimum required permissions are INTERNET, ACCESS_WIFI_STATE, and ACCESS_NETWORK_STATE, which are 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_2_1_7.zip and unzip the file. The resulting vrtcal-sdk directory will have the following files:

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.

Setting UnifID Identity Management Data (Optional)

We support email and phone number data types. Use the following to set user email:

       VrtcalSdk.setPiiData(PiiDataType.EMAIL, "user_mail"); 

To set user phone number, use the following (you can use any phone number format, since the SDK will take care of cleaning up the string):

       VrtcalSdk.setPiiData(PiiDataType.PHONE_NUMBER, "user_phone_number"); 

You should only set either email or phone number. Invoking the above API again will override the previous value. Ideally, you should call it before your first ad request.

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

    @Override
    public void onAdVideoStarted(VrtcalBanner banner) {
    }

    @Override
    public void onAdVideoCompleted(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. The onAdVideoStarted() and onAdVideoCompleted() callbacks are only applicable to VAST ads. If you have video content in your app, you should pause your video when onAdVideoStarted() is called to avoid conflicts. You can resume playback when onAdVideoCompleted() is invoked. If you reload banners manually to maximize ad revenue, the onAdVideoCompleted() callback can be used as a good indication that the ad has completed and thus is a good time to load a new banner.

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.

Showing Digital Audio (DAAST) Ads

Create digital audio ad

Create a digital audio ad by instantiating a VrtcalDigitalAudio view.

VrtcalDigitalAudio digitalAudio = new VrtcalDigitalAudio(context);

Configure digital audio ad

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

digitalAudio.setAdListener(new VrtcalDigitalAudioListener() {
    @Override
    public void onAdLoaded(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }

    @Override
    public void onAdFailedToLoad(VrtcalDigitalAudio vrtcalDigitalAudio,
	    Reason reason) {
    }

    @Override
    public void onAdStarted(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }

    @Override
    public void onAdFailedToStart(VrtcalDigitalAudio vrtcalDigitalAudio,
	    Reason reason) {
    }

    @Override
    public void onAdClicked(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }

    @Override
    public void onAdAudioStarted(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }

    @Override
    public void onAdAudioCompleted(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }

    @Override
    public void onAdDismissed(VrtcalDigitalAudio vrtcalDigitalAudio) {
    }
});

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() and onAdFailedToStart() callbacks, the SDK provides a reason that could aid in debugging why an ad request failed.

The onAdAudioStarted() and onAdAudioCompleted() callbacks inform you that media has started and ended, respectively. If you have media content in your app, you should pause your media when onAdAudioStarted() is called to avoid conflicts. You can resume playback when onAdAudioCompleted() is invoked. The onAdDismissed() callback indicates that user skipped the ad (only applies to skippable ads). When the ad is skipped, the audio will stop, but the ad view is controlled by the app and will still be visible. It is the app’s responsibility to call destroy() on the ad object and remove the VrtcalDigitalAudio ad view from UI.

Loading digital audio ad

Playing a digital audio ad is a two-step operation: load, and start. Load the digital audio ad with the following call:

digitalAudio.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.

Starting digital audio ad

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

digitalAudio.startAd();

Adding ad view(320×50) to UI (Optional)

You can optionally add the ad view to the UI instead of having your audio ad play only in the backgroud as it will have a companion banner present, as follows:

ViewGroup adViewContainer = findViewById(R.id.ad_view_container);
adViewContainer.addView(digitalAudio);

NOTE: Digital Audio Ads will ALWAYS have a 320×50 companion banner available for optional use. If the advertiser supplies a companion banner, it will be present. If no advertiser companion banner is supplied, a generic companion banner will be present.

Destroy digital audio ad

The digital audio ad will remain in memory after audio playback completes. This allows the companion ad (if applicable) to remain on UI. It is the app’s responsibility to remove ad views (if previously added) and destroy the ad object when the digital audio ad is no longer needed, as follows:

// Applicable only if you had previously added the digitalAudio ad view
ViewGroup adViewContainer = findViewById(R.id.ad_view_container);
adViewContainer.removeView(digitalAudio);

// Destroy ad object
digitalAudio.destroy();
digitalAudio = null;

SDK Native Ads Integration Guide

Integration Strategy

We support manual integration with raw native ad data.  This integration strategy only provides native ad data and does not dictate how the ad is to be displayed, allowing the most flexibility.  For example, your app might be a web app, and using this type of integration allows you to display the native ad in HTML format, and not be tied to Android View objects.

Loading Native Ads

Create Native Ad

Create a native ad by instantiating a VrtcalNativeAd object:

VrtcalNativeAd nativeAd = new VrtcalNativeAd(context);

Configure Native Ad

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

nativeAd.setLoadListener(new VrtcalNativeLoadListener() {
         @Override
         public void onAdLoaded(VrtcalNativeAd nativeAd) {
         }

         @Override
         pubic void onAdFialuedToLoad(VrtcalNativeAd nativeAd, Reason reason) {
         }
});

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

if (nativeAd.getTitle() != null) {
    String title = nativeAd.getTitle();
    // Display Title
}

However, if the value is not null, you must display it on your ad.

Click Events

When user taps on a native ad, you must retrieve the click landing page URL from nativeAd.getClickLandingUrl(), and handle the URL based on the protocol, e.g. open web browser and display page.

Destroying Native Ad

When a VrtcalNativeAd object is no longer needed, you must destroy it to release the resources, as follows:

nativeAd.destroy();
null;

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.

Banner Refresh

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 Google SDKs [AdMob/GAM])

If your app is integrated with VRTCAL SDK, and you want the ability to serve Google SDKs [AdMob/GAM] ads through our SDK, follow these instructions:

1. 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.
2. Integrate Google SDK: Set up your project following instructions provided by Google. You only need to do the steps listed below. You should not do the code integration.
   • Import the Mobile Ads SDK
   • Update your AndroidManifest.xml
3. Ad unit and line item configuration:
   • If you have not done so already, create the Google ad units from Google’s website

   • Add your Google app and 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 “AdMob” as the Line Item Type. See the VRTCAL UI reference guide here for additional details: SDK UI Doc

4. Add custom event library to your project:
   • If you had integrated with a previous version of our SDK, delete all files in <proj>/app/src/main/java/com/vrtcal/sdk/customevent. directory. (We used to ship custom events as source files, but they are now packaged in AAR files.)

   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-admob.aar to your project’s libs directory <proj>/app/libs.

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

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

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

Ad Mediation (Google SDKs [AdMob/GAM] to VRTCAL)

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

1. Integrate Google SDK: Follow Google’s instructions on how to integrate their SDK into your project, including the code integration instructions.
2. 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.
   • Download the SDK
   • Project Configuration
   • ProGuard (if applicable)
   • GDPR (if applicable)
   • MRAID (if applicable)
3. VRTCAL ad 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.
4. Google ad configuration
   • Go to Google’s website

   • If you have not done so already, create your app, and select your newly created app.

   • Go to Ad units, and click Add Ad Unit button. Follow instructions to finish creating the ad unit. Repeat for each ad unit needed. We currently support Banner and Interstitial ad formats.
   • Go to Mediation, and click on Create Mediation Group button
   • Select the desired ad format, and select Android for platform. Click Continue.
   • Follow instructions to fill out the values. Click Add Ad Units. Select the ad unit unit you want to add to the mediation group, and click Done.
   • Click Add Custom Event. Follow instructions to specify label and eCPM. Click Continue.
   • Enter the following for class name and parameter (use the same class name for both banner and interstitial custom events):Class name:

     com.vrtcal.sdk.customevent.AdMobVrtcalCustomEvent

     Parameter:

     {"appId":vrtcal_app_id,"zoneId":vrtcal_ad_unit_id}

      

     Where vrtcal_app_id and vrtcal_ad_unit_id are the VRTCAL app ID and ad unit ID that you created previously, e.g.:

     {"appId":11073,"zoneId":10005}

      

   • Finish creating your custom event, and click Save to save your mediation group.
5. Add custom event library to your project:
   • If you had integrated with a previous version of our SDK, delete all files in <proj>/app/src/main/java/com/vrtcal/sdk/customevent directory. (We used to ship custom events as source files, but they are now packaged in AAR files.)

   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-admob.aar to your project’s libs directory <proj>/app/libs.

   • Open /app/build.gradle and add the following line to the dependencies section:

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

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

Ad Mediation (VRTCAL to IronSource)

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

1. 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.
2. Integrate IronSource SDK: Set up your project following instructions provided by IronSource. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Add the IronSource SDK to Your Project
   • Step 2. Set Google Identifier Permissions
   • Step 3. Initialize the SDK
3. Ad unit and line item configuration:
   • From the IronSource Dashboard: Create the IronSource ad units on IronSource’s website
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the IronSource network to. Make sure to choose “IronSource” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-ironsource.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (IronSource to VRTCAL)

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

1. Integrate IronSource SDK: Follow IronSource’s instructions on how to integrate their SDK into your project, including the code integration instructions.
2. 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)
3. 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.
   • From IronSource’s Dashboard:
     • Create custom adapter with network key 15ba70bc5 (this is the network key for the VRTCAL custom adapter)
     • Edit the newly created custom adapter as follows: Enter you VRTCAL app ID under the AppID input field, then click on the Interstitial tab and enter your zone ID for ZoneID input field. If you have rewarded video, repeat the above on the Rewarded Video tab.
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-ironsource.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following line to the dependencies section:

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

      

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

Ad Mediation (VRTCAL to AppLovin)

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

1. 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.
2. Integrate AppLovin SDK: Set up your project following instructions provided by AppLovin. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Add the AppLovin SDK to Your Project
   • Step 2. Add the SDK Key
3. Ad unit and line item configuration:
   • From the AppLovin Dashboard: Create the AppLovin ad units on AppLovin’s website
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the AppLovin network to. Make sure to choose “AppLovin” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-applovin.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (AppLovin to VRTCAL)

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

1. Integrate AppLovin SDK: Follow AppLovin’s instructions on how to integrate their SDK into your project, including the code integration instructions.
2. 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)
3. 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.
   • From AppLovin’s Dashboard:
     • Go to Networks, scroll to the bottom, and click on “Click here to add a Custom Network”. On the resulting Manage Network page, do the following
       1. Select SDK for Network Type
       2. Enter “VRTCAL” for Custom Network Name
       3. Enter “com.vrtcal.sdk.customevent.AppLovinVrtcalCustomEvent” for Android/Fire OS Adapter Class Name
       4. Click Save
     • Go to Ad Units. Create a new ad unit, or select the ad unit you wish to mediate to VRTCAL. On the ad unit page, scroll down to Custom Networks & Deals section, and do the following:
       1. Expand the VRTCAL custom network
       2. Activate the custom network by sliding the Status slider to On position
       3. Enter you VRTCAL app ID in the App ID input field
       4. Enter your VRTCAL zone ID in the Placement ID input field
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-applovin.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following line to the dependencies section:

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

      

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

Ad Mediation (VRTCAL to Fyber-FairBid)

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

1. 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.
2. Integrate Fyber-FairBid SDK: Set up your project following instructions provided by Fyber-FairBid. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Integration
   • Step 2. Modify Your Manifest.xml
3. Ad unit and line item configuration:
   • From the Fyber-FairBid Dashboard: Create the Fyber-FairBid ad units on Fyber-FairBid’s website
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the Fyber-FairBid network to. Make sure to choose “Fyber-FairBid” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-fyber.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (VRTCAL to Fyber-Marketplace)

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

1. 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.
2. Integrate Fyber-Marketplace SDK: Set up your project following instructions provided by Fyber-MarketPlace. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Integration
   • Step 2. Modify Your Manifest.xml
3. Ad unit and line item configuration:
   • From the Fyber-MarketPlace Dashboard: Create the Fyber-MarketPlace ad units on Fyber-Marketplace’s website
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the Fyber-Marketplace network to. Make sure to choose “Fyber-Marketplace” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-fyber.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (VRTCAL to Smaato)

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

1. 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.
2. Integrate Smaato SDK: Set up your project following instructions provided by Smaato. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Configure your Android project
   • Step 2. Proguard Configuration
3. Ad unit and line item configuration:
   • From the Smaato Dashboard: If you have not done so already, create the Smaato publisher ID and ad space IDs
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the Smaato network to. Make sure to choose “Smaato” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-smaato.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (VRTCAL to Tapjoy)

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

1. 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.
2. Integrate Tapjoy SDK: Set up your project following instructions provided by Tapjoy. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. SDK Integration
3. Ad unit and line item configuration:
   • From the Tapjoy Dashboard: If you have not done so already, create the Tapjoy SDK key and placement names.
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the Tapjoy network to. Make sure to choose “Tapjoy” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-tapjoy.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

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

Ad Mediation (VRTCAL to Vungle)

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

1. 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.
2. Integrate Vungle SDK: Set up your project following instructions provided by Vungle. You only need to do the steps listed below. You should not do the code integration.
   • Step 1. Include the Vungle SDK in your project
3. Ad unit and line item configuration:
   • From the Vungle Dashboard: If you have not done so already, create the Vungle ad units
   • From the VRTCAL Dashboard: Go to the “manage line items” selection of the ad unit you wish to add the Vungle network to. Make sure to choose “Vungle” as the Line Item Type. See the VRTCAL UI guide HERE for additional details
4. Add custom event library to your project:
   • Go to the directory where you unzipped our SDK. Copy mediation/vrtcal-customevent-vungle.aar to your project’s libs directory /app/libs.
   • Open /app/build.gradle and add the following lines to the dependencies section:

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

The VRTCAL ad unit should now serve Vungle ads (depending on your ad unit configuration you might not always see Vungle 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 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: 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.