Manual for Android SDK

Introduction

Voice Ads allow users to engage with ads using their voice. While listening to an audio ad or watchıng a video ad, users can speak various voice commands which will be introduced to users within ad creative.

When a user says any of the following: Skip it, Next, Cancel or Not Interested, Etc., the advertisement stops and the next one plays if there is one scheduled.

When the user engages with an ad, we perform the requested action, e.g. ‘open browser’ ‘playing successive message with more details’ etc.

User responses can be ‘positive’ when users want to ‘know more’ or ‘make a purchase’ or ‘negative’ when users say ‘no’, ‘I’m not interested’

To fully enable the App, microphone access permission needs to be activated to your App manifest. You can learn more about how to do this via the following link:

Example Manifest

Please note that the application must be developed as a foreground service. And the foreground service must be launched while the activity is visible. Microphone access must be declared for foreground service as well. Please see the link below for reference:

https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running#declare-foreground-service-types-manifest

For an actual example of foreground service, please click HERE

(Please turn off the AdBlocker to access the repository)

SDK Installation

Install the SDK from our repository as described below or use the open-source version. The open-source version of SDK can be found HERE

Please note, that any change in the code will affect the performance and revenue.

The most recent version of our SDK is 9.4.0

Please note, that the Demo project you can find in the open-source version shouldn't be used for integration. The aim of the project is to demonstrate the technology. It shouldn't be inserted into the application in any way.

Project Configuration

repositories {
   jcenter()
   mavenCentral()
   maven {
       url 'https://instreamatic.com/nexus/repository/maven-public'
   }
}
	ext {
   admanVersion = '9.4.0'
   serVersion = '6.15.0'
   admanEmbdVersion = '1.1.0'
   androidSupportVersion = '25.3.1'
	}
	dependencies {      
    api 'com.squareup.okhttp3:okhttp:4.10.0'

    api 'com.android.support:support-v4:' + project.ext.androidSupportVersion
    api 'com.android.support:design:' + project.ext.androidSupportVersion

    api 'com.instreamatic:adman-android:' + project.ext.admanVersion + '@aar'
    api 'com.instreamatic:adman-android-view:' + project.ext.admanVersion + '@aar'
    api 'com.instreamatic:adman-android-voice:' + project.ext.admanVersion + '@aar'
    api 'com.sensory.speech.snsr:tnl:'+ project.ext.serVersion +'@aar'
    api 'com.instreamatic.embedded:voice-recognition-embedded:' + project.ext.admanEmbdVersion + '@aar'
    api 'com.instreamatic.embedded:phrase-spot:' + project.ext.admanEmbdVersion + '@aar'
    
    }
}
	android {
   ...
   packagingOptions {
       exclude 'META-INF/DEPENDENCIES.txt'
       exclude 'META-INF/LICENSE.txt'
       exclude 'META-INF/NOTICE.txt'
       exclude 'META-INF/NOTICE'
       exclude 'META-INF/LICENSE'
       exclude 'META-INF/DEPENDENCIES'
       exclude 'META-INF/notice.txt'
       exclude 'META-INF/license.txt'
       exclude 'META-INF/dependencies.txt'
       exclude 'META-INF/LGPL2.1'
   }
   
}

Code Example

Please find the basic integration example below:

package com.instreamatic.adman.demo.base;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;

import com.instreamatic.adman.Adman;
import com.instreamatic.adman.AdmanRequest;
import com.instreamatic.adman.IAdman;
import com.instreamatic.adman.Region;
import com.instreamatic.adman.view.generic.DefaultAdmanView;

public class DemoAdmanActivity extends Activity {
    final private static String TAG = "DemoAdman";
    private IAdman adman;
    private View startView;
    
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.demo_adman_activity);
        AdmanRequest request = new AdmanRequest.Builder()
                .setSiteId(1249)
                .setRegion(Region.GLOBAL)
                .setType(Type.VOICE)
                .build();
        adman = new Adman(this, request);
        adman.bindModule(new DefaultAdmanView(this));
        AdmanVoice admanVoice = new AdmanVoice(this)
	      adman.bindModule(admanVoice);
	      VoiceRecognitionEmbedded voiceRecognition = new VoiceRecognitionEmbedded(this);
	      voiceRecognition.addModel("assets/models/large_instrmtc_ovr25_enUS.snsr", LanguageCode.ENGLISH_US);
	      admanVoice.setVoiceRecognition(voiceRecognition);
        startView = findViewById(R.id.start);
        startView.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                adman.start();
            }
        });
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        adman.pause();
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        adman.play();
    }
}

Your ID will be specified by our support team. Please, note that ID 1249 is used for testing purposes only.

After the integration and testing, you will be supplied with the production ID and for those who use the global server, region GLOBAL should be used and for EU server region EUROPE should be used.

On-Device Recognition

On-device recognition feature is enabled by default for a limited amount of languages (see below). The rest of the languages will be processed via cloud-based recognition.

On-device recognition requires at least one active model to be specified.

If you want to add more models for on-device recognition, add one more VoiceRecognitionEmbedded::addModel with another model.

Click here to get on-device recognition models

List of available models (more to come):

Language	Language Code	Filename
en-US	ENGLISH_US	large_instrmtc_ovr25_enUS.snsr
ru-RU	RUSSIAN	large_instrmtc_ovr50_ruRu.snsr
de-DE	GERMAN	large_instrmtc_ovr50_deDE.snsr

If you can't find the desired language in the list or do not want to use the on-device recognition, you can remove all the related code and libraries.

Implementation Details

You need to call adman.sendCanShow() in any case when you suppose to play an ad, even if you haven't received any. This method should be called at any possible ad placement in the app. This is very important and will dramatically affect the revenue.

To preload an ad, the below method should be used:

adman.preload();

In case of successful preload, you will receive AdmanEvent.Type.READY as a response. In case when there are no ads for a certain listener you will receive AdmanEvent.Type.NONE as a response.

In case of error or lost connection, you will receive AdmanEvent.FAILED as a response.

The basic construction for the ad playback will look as follows:

//App is started. 
//You are preloading ad at the start of the session
//After the init of the SDK you are preloading an ad:
adman.preload();
//wait for an ad placement.
//For example it's a pre-roll and 'play' button is pressed:
adman.sendCanShow();
//Here you will need to check if there is an ad available for playback
//If the state of Adman is AdmanEvent.Type.READY then ad must be played
adman.play();
//if there is no ad available, return listener to a content and try requesting another ad

Please see our examples above for a more detailed snippet.

If you want to play an ad right after the preload, you can use the following solution:

//Ad placement 
//For example it's a pre-roll and 'play' button is pressed:
adman.sendCanShow();
//then
adman.start();
//if there is no ad available, return listener to a content and try requesting another ad

After the ad playback, the listener should be returned to content and another ad should be requested for the next ad break.

Also, please note that you should manage AudioFocus when working with SDK according to this official documentation: https://developer.android.com/guide/topics/media-apps/audio-focus

You should grant AudioFocus when our SDK will be requesting it in order to ensure, that ads will not overplay the content. Please see our example above in order to see how it should work.

You can find the list of available methods HERE

The list of Adman player events can be found HERE

For frequently asked questions, please see our FAQ Page below

pageAndroid SDK FAQ

Voice Video Ads Implementation

Please skip this part if you are not going to add Voice Video Ads to your app.

Add the following to your build.gradle:

android {
...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
...
}    

dependencies {
...
    api 'com.google.android.exoplayer:exoplayer-hls:2.18.5'
    api 'com.google.android.exoplayer:exoplayer-core:2.18.5'
    api 'com.google.android.exoplayer:exoplayer-ui:2.18.5'
    api 'com.squareup.picasso:picasso:2.71828'
    api 'jp.wasabeef:picasso-transformations:2.2.1'
...
    api 'com.instreamatic:adman-android-view-video:' + project.ext.admanVersion + '@aar'
...
}

Add the view module for Video Ads:

adman.bindModule(new DefaultAdmanVideoView(this))

To use both Voice Ads and Voice Video Ads, make sure you have both AdmanVideoView and AdmanView available.

Use the below parameters to configure the Voice Video Ad request:

region = Region.GLOBAL;
    siteId = 2177;
    slot = Slot.ANY;
    type = Type.VOICE_VIDEO;

The above ID can be used for testing purposes only.

If you need to switch between Voice Ads and Voice Video Ads, add the following when updating the request parameters. Update the parameters before preloading an ad.

adman.updateRequest(request_builder, true);

Usage example:

AdmanRequest request = new AdmanRequest.Builder()
                .setSiteId(2177)
                .setRegion(Region.GLOBAL)
                .setSlot(Slot.ANY);
                .setType(Type.VOICE_VIDEO)
 adman.updateRequest(request_builder, true);

You can use the same way to switch back to Voice Ads.

Click HERE for the demo app.

How to test the integration?

After the integration, you will be getting unlimited Voice Ads for all your ad requests. Please make sure that the ad is reacting to your commands in the way it's expected. Test for Positive, Negative, and Swear words (if needed), etc.

How to send bug reports?

If you encounter any bugs during testing, please report all bugs and reports to the following email [e-mail] .

In the event of unusual behavior (wrong responses, advertisement skipping, etc.), please send all incidents along with a description of the incident and your advertising ID. This will allow us to analyze what happened and correct the issue. We do advise that for multiple incidents, to send them in one email so we can give you or full attention and address these incidents. Incidents sent to use one at a time may have a longer than normal response time. Incidences may be reported to the following email [e-mail] .

In the event of a crash, please send all crash logs and/or reports to the following email [e-mail] .

For frequently asked questions, please see our FAQ Page below

pageAndroid SDK FAQ

Why SDK?

Your decision to make Instreamatic Dialogue Ads available on your native mobile apps will provide a highly valuable and unique audio communication capability that makes audio or video ads “smart”. These ads are driven by Voice AI and allow the listener to respond to various scenarios with voice commands that drive target actions.

The Instreamatic SDK is the most simple and hassle-free way to integrate Dialogue ads to your app. There will be no need for complex coding or fine-tuning, just integrate our SDK by following this short manual and you are ready to go. The whole installation should only take an hour or so for a qualified tech professional and we will support your installation all through the process.

Is it safe?

Yes, our SDK is completely safe for your app and your users. Upon your request, we will share our tech specifications, so you can easily check for yourself that our SDK is completely safe for using it in your apps. You will have the full support from us during the integration process and even afterwards. Our SDK was tested on all Apple devices available in the market, so the possibility of a crash has been eliminated. You can implement in a test environment first to review with your QA team to become absolutely comfortable and again, we will support you through the entire process.

What kind of support can I expect?

Our support team is available by email during business hours on weekdays in most time zones. We also provide detailed installation manuals that provide clear instructions and answer most all questions. We will also answer the questions during the initial integration. Please note, that you should provide all the information regarding the issues during the integration if you need support from our side.

For frequently asked questions, please see our FAQ Page below

pageAndroid SDK FAQ

What to do if I do not want to use SDK?

You can contact your account manager or support team in order to get tech specifications of the protocol we are using. With our documentation, you will be able to build your own integration, but please keep in mind that you will need to perform some complex coding in order to build the integration. We will still provide support if you decide to take this option.

Feel free to contact our support at [e-mail]