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

Project Configuration

repositories {
jcenter()
mavenCentral()
maven {
url 'http://instreamatic.com/nexus/repository/maven-public'
}
}
ext {
admanVersion = '7.17.6'
androidSupportVersion = '25.3.1'
}
dependencies {
compile('com.squareup.okhttp3:okhttp:3.10.0')
compile('com.instreamatic:adman-android:' + project.ext.admanVersion + '@aar')
compile('com.instreamatic:adman-android-view:' + project.ext.admanVersion + '@aar')
compile('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. Ads will be requested by the timer (only used for demonstration purposes).

Integration Example Code

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

During the initial integration only ID 1063 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.

When receiving 'NONE', 'FAILED' or 'ERROR', a listener should be returned to content.

After the ad playback, listener should be returned to content as well.

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