Manual for Android SDK

Introduction

Voice Ads allow users to engage with ads using their voice. While listening to an audio 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 audio 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 links:

​For Android before 6.0​

​For Android 6.0 and up​

(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​

The most recent version of our SDK is 7.17.39

Project Configuration

repositories {
   jcenter()
   mavenCentral()
   maven {
       url 'http://instreamatic.com/nexus/repository/maven-public'
   }
}
	ext {
   admanVersion = '7.17.39'
   androidSupportVersion = '25.3.1'
	}
	dependencies {      
    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'
    
    }
}
	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));
        adman.bindModule(new AdmanVoice(this));
        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();
    }
}

​Example in our repository​

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.

Implementation Details

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.

For SDK versions below 7.17.37, you may receive AdmanEvent.Type.ERROR in case of error. 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

​

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 working as it demonstrated in the video above.

For the final test and verification, please send the test build to support@instreamatic.com

How to send bug reports?

If you encounter any bugs during testing, please report all bugs and reports to the following email support@instreamatic.com .

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 support@instreamatic.com .

In the event of a crash, please send all crash logs and/or reports to the following email support@instreamatic.com .

For frequently asked questions, please see our FAQ Page below

​

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

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 support@instreamatic.com