Manual for Android SDK

Introduction

Dialogue 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 say’s 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

For Android API version of 28 and above, the application must be developed as foreground service. Please see the link below for reference:

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

Project Configuration

repositories {
jcenter()
mavenCentral()
maven {
url 'http://instreamatic.com/nexus/repository/maven-public'
}
}
ext {
admanVersion = '7.17.36'
androidSupportVersion = '25.3.1'
}
dependencies {
api 'com.squareup.okhttp3:okhttp:3.10.0'
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 link to the implementation example below.

Once your project is properly configured, you can use this example to understand how to inject Instreamatic Dialogue ads into your Android app. The example consists of two parts: Activity and Service, which are used to play sample audio content and Ads.

In this example our SDK is used to run an ad every 90 seconds for illustrative purposes, for your app please implement the SDK according to your product logic.

Integration Example Code

Please note that Demo app is only used to demonstrate the SDK integration and it shouldn't be used as a basis for real application.

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

During the initial integration only ID 1249 and region GLOBAL must be used.

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

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.

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 is no ads for the certain listener you will receive AdmanEvent.Type.NONE as a response.

In case of error you will receive AdmanEvent.Type.ERROR as a response.

In case of 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.

After the ad playback, 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 below 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?

Please check the page below in order to find out how to test the integration:

Reference Manual

The Javadoc have the descriptions of the classes that are required and are currently available at http://instreamatic.com/demo/android/doc/index.html

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.

And our SDK is now listed on the SafeDK marketplace which means it has passed security and compatibility checks. This test and review by SafeDK provides users assurance that our SDK is both stable and secure so your data is safe.

You can find our SDK here on the marketplace - https://www.safedk.com/marketplace/sdks/instreamatic-adman

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