Download Android Second Screen SDK Quick Start Guide

Android Second Screen SDK
Quick Start Guide
Version 1.0 · 01/17/2013
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
Android Second Screen SDK · Quick Start Guide · Version 1.0
Table of Contents
Table of Contents ........................................................................................................................................ 2
1. Status ........................................................................................................................................................ 3
2. Introduction .............................................................................................................................................. 4
2.1 Modes ............................................................................................................................................. 4
2.2 Workflows ....................................................................................................................................... 5
3. Requirements........................................................................................................................................... 6
3.1 Device .............................................................................................................................................. 6
3.2 Development Environment ............................................................................................................. 6
4. Initial Setup ............................................................................................................................................. 7
4.1 Setup Eclipse Workshop.................................................................................................................. 7
4.2 Eclipse Project Configuration .......................................................................................................... 8
4.3 Setting Up The Libraries ................................................................................................................ 10
5. Usage ...................................................................................................................................................... 13
5.1 General Usage Notes..................................................................................................................... 13
5.2 Notification-based Initialization All notification-based solutions follow the procedure below.
The only thing that should generally change is the channelName and subscriberKey. ..................... 14
5.3 Sampling-based Initialization ........................................................................................................ 16
5.4 Returning the content string for ad URL ....................................................................................... 18
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
2
Android Second Screen SDK · Quick Start Guide · Version 1.0
1. Status
Contributor Date
Version Description
Brian Bober 10/22/2012 0.1.0
• Original version on Confluence
Brian Bober 12/10/2012 0.1.1
Brian Bober 1/14/2013
0.1.2
Brian Bober 1/17/2013
1.0.0
•
•
•
•
•
•
•
•
•
Broke up notification and sampling documentation
Update API usage instructions
Various cleanup
Merged notification and sampling back together
Separated developer and end-user documentation.
Updated requirements
SDK 1.0 released.
Migrated Confluence to guide, abridge as appropriate.
Migrated implementation-specific notes to reference
docs.
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
3
Android Second Screen SDK · Quick Start Guide · Version 1.0
2. Introduction
The Android Second Screen SDK is designed to match what advertisement is currently playing
on TV with a known online advertisement and provide a URL to the matching advertisement to
display on the device. It supports multiple detection algorithms, and unlike any other solution, it
is tailor-made for advertising.
Domain Diagram Overview
2.1 Modes
The SDK offers two modes of operation for detection and matching:
•
•
Sampling - Record sample and produce fingerprint/watermark to compare against known
samples.
Notification - Consumer of notification-based ad detection solutions
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
4
Android Second Screen SDK · Quick Start Guide · Version 1.0
2.2 Workflows
The roles of these two methods are described below:
•
•
Sampling
o Sample audio from advertisement on television
o Generate fingerprint/watermark code
o Send to remote server or compare locally to known matches
o If match is detected, provide mapping server URLs. Does NOT handle ad display
Notification
o Listens for ad detection event from websockets indicating channel has a matching
ad
o Returns detected ad to application. Does NOT handle ad display
It is important to highlight that the SDK Does NOT handle ad display. Ad display is up to the
app developers.
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
5
Android Second Screen SDK · Quick Start Guide · Version 1.0
3. Requirements
3.1 Device
•
•
Android version 2.3.3 or above (recommend Android version 4.1.2 or above)
Android and Google API 10 or above (recommend Android and Google API 16 or above)
Emulators are not supported due to sampling frequency limitations
3.2 Development Environment
•
•
•
Eclipse 4.2.0 + Java
Android SDK
SVN Client
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
6
Android Second Screen SDK · Quick Start Guide · Version 1.0
4. Initial Setup
4.1 Setup Eclipse Workshop
•
•
•
Install Eclipse classic, then follow instructions here to install Eclipse ADT:
http://developer.android.com/sdk/installing/installing-adt.html
o Currently using Eclipse 4.2.0
Install the Android SDK: http://developer.android.com/sdk/index.html
o App developer may need to go into the Google Android SDK Manager and
download files for target Android version for the device used for testing. (Run as
administrator).
o Make sure to get the Android SDK for the Android version of the device.
App developer will need the Google ADB driver for the device.
In the Android SDK Manager, make sure to install Google API in Eclipse for the versions of
Android being targeted by the application. Required:
•
•
•
SDK Platform
Google APIs
Sources for Android SDK
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
7
Android Second Screen SDK · Quick Start Guide · Version 1.0
Android SDK Manager
4.2 Eclipse Project Configuration
Make sure the main application's AndroidManifest.xml for the main app has the following line
(e.g. after the <uses-sdk /> ) block:
•
•
•
<uses-permission android:name="android.permission.INTERNET"/>
For sampling-based solutions, add <uses-permission
android:name="android.permission.RECORD_AUDIO"/>
For diagnostics <uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Make sure minSDKVersion is set to 10 or higher
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
8
Android Second Screen SDK · Quick Start Guide · Version 1.0
Sample AndroidManifest.xml file for a main app. Some values are application-specific:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.dgit.secondscreen.clients.android.sampleapp"
android:versionCode="1"
android:versionName="%DG_VERSION_NAME_MACRO%" >
<uses-sdk
android:minSdkVersion="10"
android:configChanges="keyboardHidden|orientation"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<application
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:theme="@style/AppTheme" >
<activity android:name="MainActivity"
android:label="@string/app_name" android:enabled="true"
android:launchMode="standard">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
</activity>
</application>
</manifest>
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
9
Android Second Screen SDK · Quick Start Guide · Version 1.0
4.3 Setting Up The Libraries
•
•
The app developer should be provided a zip that contains some or all of the following
JAR files. DG may tailor the Jar files to the application’s specific needs, so the developer
may not receive all of them. The full list is: audiblemagicwrapper, commoninterfaces,
echoprintwrapper, libjavawebsocket, network, notificationwrapper, secondscreensdk
Make sure the correct .jar files are included. Please refer to the accompanying Reference
PDF specific to the solution for more details on exactly which Jar files are needed, in
order to reduce memory usage. Geenrally:
o On Libraries tab of project properties > build configuration, make sure that
secondscreensdk.jar, commoninterfaces.jar, notificationwrapper.jar, and
network.jar is present, along with any Android-required jars.
o For notification-based solutions, also verify that notificationwrapper.jar and
libjavawebsocket.jar is included
o For sampling-based solutions, verify that the individual solution Jar for that
sampling solution is included. Currently, either audiblemagicwrapper.jar or
echoprintwrapper.jar
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
10
Android Second Screen SDK · Quick Start Guide · Version 1.0
Imported JAR libraries - sampling
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
11
Android Second Screen SDK · Quick Start Guide · Version 1.0
Imported JAR libraries - notification
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
12
Android Second Screen SDK · Quick Start Guide · Version 1.0
5. Usage
5.1 General Usage Notes
The current implementation of the Second Screen SDK DOES NOT handle ad display (e.g.
ORMMA/MRAID). That is up to the application developer to support.
The Android SDK API follows the facade pattern and observer pattern. The API does not intend
to follow the MVC pattern because it does not have a user-interface, and therefore no views.
However, the app developer can easily integrate it into an application that uses the MVC by
having the controller use the APIManager class and the controller pass along the content string
from MatchModel.
The Android SDK API is broken up into the following main packages available for model:
•
com.dgit.secondscreen.android.api.common.manager - Includes the main manager classes
•
•
com.dgit.secondscreen.android.api.config - Used for configuration
com.dgit.secondscreen.android.api.common.manager.events.listeners - Includes
APIManagerListener, which should be implemented by a class in the main application
Make sure to follow the instructions above to import the necessary Jar files, and preferably no
more than is required.
The application developer will need to create an instance of the ConfigOptions class and place it
in the same package. Since this class is still likely to be expanded upon in the future, it is
recommended DG provide one based on the application’s needs.
General procedure
The general procedure is that the app developer makes an instance to the implementation class
for a specific solution, and binds it to the APIManager interface. From that point on, the app
developer references the APIManager interface. At minimum, implementation-specific
instructions related to the solution being invoked (e.g. Echoprint, notification, etc) are included
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
13
Android Second Screen SDK · Quick Start Guide · Version 1.0
in docs that should have been provided along with this main guide.
Solution-specific instructions
Make sure to follow the instructions under “Initial Setup” to import the necessary Jar files.
Also, make sure to look in the accompanying documentation for more specific instructions
related to the solution the application intends to employ.
5.2 Notification-based Initialization
All notification-based solutions follow the procedure below. The only thing that should generally
change is the channelName and subscriberKey.
Step 1.
The following code shows an example class header, along with imports, how to implement
APIManagerListener, and variables to define for later code examples.
import com.dgit.secondscreen.android.api.common.manager.NotificationManager;
import com.dgit.secondscreen.android.api.common.manager.APIManager;
import
com.dgit.secondscreen.android.api.common.manager.events.listeners.APIManagerL
istener;
import com.dgit.secondscreen.android.api.common.model.MatchModel;
public class MainActivity extends Activity implements APIManagerListener
{
APIManager apiManager;
Step 2.
For this step, verify DG has provided the app developer something like the following:
The app developer should have been provided:
•
A subscriptionURL e.g.
"http://devsecondscreen.eyewonderlabs.com:80/NotificationServiceSwitchboard/Register
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
14
Android Second Screen SDK · Quick Start Guide · Version 1.0
•
•
.ashx";
A channelName e.g. "TestChannel:DGTV"; (warning: For illustration only, do not use)
A subscriberKey e.g."7bb667d3-f3f7-4402-95c3-af46f54b7997"; (warning: For
illustration only, do not use)
The following code is used to initiate notification. Note that startListening() actually means
"begin listening for notifications" in this case.
“this”, shown below, is expected to be of type Activity.
apiManager = new NotificationManagerImpl(this, subscriptionURL, channelName,
subscriberKey);
setAPIManagerListener(this);
apiManager.startListening();
Step 3.
Implement onMatchServiceCompleted and onListeningFailed (ignore seq, which doesn't apply
for notification-based solutions). m.isGood tells if there is a match. Make sure to check for null.
public void onMatchServiceCompleted(MatchModel m, int seq)
{
if ((m!= null && m.isGood()))
{
String contentString = m.getContentString());
// Do something with it. Suggested verify this content string
is not already loaded. e.g.:
// if (!isAlreadyLoaded(contentString)) loadAd(contentString);
}
}
public void onListeningFailed(String reason, int seq)
{
// Handle the error, perhaps try listening again
}
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
15
Android Second Screen SDK · Quick Start Guide · Version 1.0
5.3 Sampling-based Initialization
The example below uses Echoprint. Other sampling solutions will vary in terms of what
implementation class the app developer will use (e.g. instead of EchoprintManagerImpl, another
class). See the other guides included with this one for more specific instructions.
Step 1.
The following code shows an example class header, along with imports, how to implement
APIManagerListener, and variables to define for later code examples.
The application developer will need to create an instances of ConfigOptions class and place it in
the same package. It is recommended that DG provide one based on the application’s needs
import com.dgit.secondscreen.android.echoprint.EchoprintManagerImpl;
import com.dgit.secondscreen.android.api.common.manager.APIManager;
import
com.dgit.secondscreen.android.api.common.manager.events.listeners.APIManagerL
istener;
import com.dgit.secondscreen.android.api.common.model.MatchModel;
public class MainActivity extends Activity implements APIManagerListener
{
APIManager apiManager;
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
16
Android Second Screen SDK · Quick Start Guide · Version 1.0
Step 2.
For this step, use one of the sampling libraries such as EchoprintManager or
AudibleManagicManager. See the accompanying documentation based on the solution being
used to determine how to initiate the specific solution the application is using.
“this”, shown below, is expected to be of type Activity.
apiManager = new EchoprintManagerImpl(this);
apiManager.setAPIManagerListener(this);
apiManager.startListening();
Step 3.
Implement onMatchServiceCompleted. Seq is a variable that is useful to link up calls to
onMatchServiceCompleted with lines outputted in logcat.
m.isGood tells if there is a match. Make sure to check for null.
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
17
Android Second Screen SDK · Quick Start Guide · Version 1.0
public void onMatchServiceCompleted(MatchModel m, int seq)
{
if ((m!= null && m.isGood()))
{
String contentString = m.getContentString());
// Do something with it. Suggested verify this content string
is not already loaded. e.g.:
if (!isAlreadyLoaded(contentString)) loadAd(contentString);
}
}
public void onListeningFailed(String reason, int seq)
{
// Handle the error, perhaps try listening again
}
Warning: Don’t run in an emulator because the emulator is limited to 8,000 hz. Applications
will error out in such case.
5.4 Returning the content string for ad URL
The content string will be returned in the form of a URL
Recall the sample code above (copied below) showing an example of using the MatchModel to
return an ad URL.
String contentString = m.getContentString());
// Do something with it. Suggested verify this content string is not already
loaded. e.g.:
if (!isAlreadyLoaded(contentString)) loadAd(contentString);
isAlreadyLoaded and loadAd are imaginary methods that would be defined by the app developer.
Obviously, the code above is just an example, and the app developer is free to handle
contentString in any way he or she chooses.
p . 9 7 2.5 8 1.2 0 00
f . 9 7 2.5 8 1.2 0 01
7 5 0 W e s t Jo h n C ar p e n te r Fr e ew ay, S u it e 70 0 | I rv i n g, T X 75 03 9
18