Android Integration Guide

Introduction

This is a guide to help you integrate Streamlyzer plug-in to your Android application.

Requirements

  1. Android development environment with SDK 14+
  2. Add the following permissions to the tag in your AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

Observers and Properties

Overview

There are 4 types of events to track (aka Observer components),

  • playbackObserver for tracking media playback.
  • userDefinedObserver for tracking user defined events.
  • sharedContentObserver for tracking sharing contents.
  • pageReferrerObserver for tracking page referrer.

There are number of properties that you should provide in order to initialize Observers.

Prior to initialization of Observers, you need to set properties as it needs. For your convenience, we group them into 5 categories. Depending on which observers you use, some of properties are required and some of them could be optional.

  • Audience properties
  • Content properties
  • Service properties
  • Platform properties
  • Customer properties

Properties

Audience properties
Variables Default Required Description
userId ‘Unset’ O User Unique ID. You should specify user unique id for each users. It shall be unique string or e-mail address or user id. It should be unique string so that data can be grouped by user id.
userType ‘Unset’ User Type. You can define the type of user. For example, “free user”, “non-free user” or “premium”.
gender ‘Unset’ User’s Gender. For example, “male” or “female”.
yearOfBirth ‘Unset’ User’s year of birth. This is for calculate user’s age. For example, “1995”.
Content properties
Variables Default Required Description
thumbnailImage ‘Unset’ URL of thumbnail image. You can specify thumbnail image of the contents. This thumbnail url will be used for displaying thumbnail image on Dashboard
seriesName ‘Unset’ Series name of movie. You can define series name of asset. For example, “Heroes”, “House of Cards”
episodeName ‘Unset’ Season/Episode name of movie. User can define Episode information into log. For example, Season 1 Episode 10 shall be “S1:E10”.
liveChannelName ‘Unset’ O Live channel Name. If the media is not a live channel, you can input the movie id.
movieId’ Unset’ O Movie ID. The tile of movie. This should be unique string so that metrics will be grouped by movie id.
movieCategory ‘Unset’ O Movie Category. You can define unique key string for grouping movie category. For example, this value can be “drama”, “comedy”, “horror” or “anime”.
movieSubcategory ‘Unset’ Movie Subcategory. You can define unique key string for grouping movie subcategroy. For example, this value can be “romantic drama”,”crime drama”, classic drama” or “teen drama”.
movieContentsProvider ‘Unset’ Movie Content providers. User can define unique key string for grouping contents providers. For example, this value can be “abc”, “desiney”, “time wanner”, “kbs” and so on.
movieRate ‘Unset’ Movie Rate. You can define movie rate. For example, “R”, “PG-13”, “PG”
bitRate 0 O Display bitrates. (unit: kbps)
resolution ‘Unset’ O Display resolutions. For example, “720×480”, “360×240”, “1080×900”, “720p”, “1080p”,”480p”
Service properties
Variables Default Required Description
live false O Is Live Service or not. If the service is Live, it shall be true, If not, it shall be false. For example, the content is VOD, it shall be “false”.
serviceType ‘Unset’ Serivce Type. You can define the type of service. For example, “TV” or “Radio”.
sessionId ‘Unset’ O Session ID. You could set session id based on each session.
streamingServerName ‘Unset’ O You can specify streaming server URL or CDN urls. It can be used for metrics grouped by streaming edge.
abTestMark ‘Unset’ O A/B test mark. This for A/B testing. You can put “A” or “B” or other unique string for A/B testing.
Platform properties
Variables Default Required Description
playerPlatformName ‘Unset’ O The named platform name. For example, “Android”, “Android Setop”
playerPlatformVersion ‘Unset’ O Player Platform Version. You can define user specific version information to group data. For example, you can specify player version information such as iOS 8, iOS 9 or iOS 9.1
mediaPlayerVersion ‘Unset’ O Media Player Version. You can define user specific version information to group data. For example, you can specify player version information such as MediaPlayer 6.
applicationName ‘Unset’ O The application name. For example, “Streamlyzer Plug-in App”
applicationVersion ‘Unset’ O The application version. For example, “1.0.0”
Customer properties
Variables Default Required Description
customerKey ‘Unset’ O Customer Key. This value is given by Streamlyzer. It is used for identifying logs you send. The log which one has invalid key value will be rejected.

Observers

Common

Description

For all observers, below three steps should be taken to set up properties.

  1. Initialize plug-in
  2. setProperties
  3. Close plug-in

// Initialize plug-in
SZRPlugin.initPlugin();

// Set properties
szrEvent.setProperties(<JSONObject>);

// close plug-in
szrEvent.closeObserver();

playbackObserver

Description
Playback Observer will be attached with media player, and monitor playback event based on user’s interaction.

How to initialize
To initialize PlaybackObserver, you should set up 3 things,

  1. Initialize plug-in
  2. Initialize playbackObserver
  3. Set proper properties on the Observer.

First, initialize plug-in and the observer and provide all of the required properties:


// Create SZRVideoView
SZRVideoView videoview = (SZRVideoView) findViewById(R.id.videoview);

// set context and properties
videoview.setContext(this);
videoview.setProperties(JSONObject);

// initialize
videoview.initialize();

// add listeners
videoview.setOnErrorListener(new MediaPlayer.OnErrorListener() {
    @Override
    public boolean onError(MediaPlayer mediaPlayer, int what, int extra) {
        // Note: Required position
        videoview.onError(what, extra);
        return false;
    }
});

videoview.setOnPreparedListener(new MediaPlayer.OnPreparedListener() {
    @Override
    public void onPrepared(MediaPlayer mediaPlayer) {
        // Note: Required position
        videoview.onPrepared();
        // Note: recommended position to start video automatically
        videoview.start();
    }
});

Implement interface Playback delegate methods

The plug-in will call these methods to collect right media status.

Function Signiture Description
isSZRPlaying It returns the player status is playing or not.
getSZRCurrentPosition It gets called to get the current position of media file. It can be the absolute position in millisecond unit. The return value should be Number, not String.
getSZRDuration It returns the total length in millisecond of the viewed media file. The return value should be Number, not String.
getSZRBufferPercentage It returns buffering percentage of playback.

Implement interface Playback status event methods

These methods are called when there is playback events.

Function Signiture Description
start It is called when the player starts.
stopPlayback It is called when the player stops.
pause It is called when the player is paused.
seekTo It is called when seek to other position.
setVideoURI It is called when the video URI is changed.

Example for SZRVideoView

Here is full example. here, we use SZRVideoView for example.


// Create SZRVideoView
SZRVideoView videoview = (SZRVideoView) findViewById(R.id.videoview);

// set context and properties
videoview.setContext(this);
videoview.setProperties(JSONObject);

// initialize
videoview.initialize();

// add listeners
videoview.setOnErrorListener(new MediaPlayer.OnErrorListener() {
    @Override
    public boolean onError(MediaPlayer mediaPlayer, int what, int extra) {
        // Note: Required position
        videoview.onError(what, extra);
        return false;
    }
});

videoview.setOnPreparedListener(new MediaPlayer.OnPreparedListener() {
    @Override
    public void onPrepared(MediaPlayer mediaPlayer) {
        // Note: Required position
        videoview.onPrepared();
        // Note: recommended position to start video automatically
        videoview.start();
    }
});

Example for Custom VideoView

Here is full example. here, we use Custom VideoView for example.


// Create Custom VideoView
CustomVideoView videoview = (CustomVideoView) findViewById(R.id.videoview);
SZRMediaPlayer szrMediaPlayer = new SZRMediaPlayer();

// implement delegate methods for playback status
szrMediaPlayer.setSZRPlaybackStatus(new SZRPlaybackStatus() {            
    @Override            
    public int getSZRCurrentPosition() {                
        return videoview.getCurrentPosition();            
    }

    @Override            
    public boolean isSZRPlaying() {
        return videoview.isPlaying();        
    }

    @Override            
    public int getSZRDuration() {                
        return videoview.getDuration();            
    }

    @Override            
    public int getSZRBufferPercentage() {                
        return videoview.getBufferPercentage();       
    }        
});

// implement playback status event methods
videoview.setSZRPlayerEvent(new SZRPlayerEvent() {
    @Override
    public void preStop() {
        szrMediaPlayer.preStop();
    }

    @Override
    public void postStop() {
        szrMediaPlayer.postStop();
    }

    @Override
    public void prePlay() {
        szrMediaPlayer.prePlay();
    }

    @Override
    public void postPlay() {
        szrMediaPlayer.postPlay();
    }

    @Override
    public void prePause() {
        szrMediaPlayer.prePause();
    }

    @Override
    public void postPause() {
        szrMediaPlayer.postPause();
    }

    @Override
    public void preSeek() {
        szrMediaPlayer.preSeek();
    }

    @Override
    public void postSeek() {
        szrMediaPlayer.postSeek();
    }

    @Override
    public void preSetMedia() {
        szrMediaPlayer.preSetMedia();
    }

    @Override
    public void postSetMedia() {
        szrMediaPlayer.postSetMedia();
    }
});

// start playback plug-in
szrMediaPlayer.initialize();

userDefinedObserver

Description

userDefinedObserver allows you to define any events that is specific to your application and your business.
– Event group is for classifying your User Defined Event.
– All should not include any spaces or special characters. For example,

  • “Media Player” – Wrong Expression (x)
  • “Media_Player” – Wrong Expression (x)
  • “MediaPlayer” – Correct Expression (o)

Please notice this, If you include any spaces or special characters, then plug-in will delete spaces and special characters. for example, plug-in send all keys as “MediaPlayer” when you try to send above properties.

How to initialize

To initialize UserDefinedEventObserver, you should set up proper properties. you can initialize observer like:


/ Initialize plug-in
SZRPlugin.initPlugin();

// Initialize User Defined Observer
SZRUserDefinedObserver szrEvent = new SZRUserDefinedObserver();
szrEvent.setContext(this);

// Set properties
szrEvent.setProperties(new JSONObject()
    // key provided by Streamlyzer
    .put(SZRConstant.CUSTOMER_KEY, "<Key Provided by Streamlyzer>")

    // end user related properties
    .put(SZRConstant.USER_ID, "<User ID>")
    .put(SZRConstant.USER_TYPE, "<User Type>")
    .put(SZRConstant.GENDER, "<User Gender>") /* SZRConstant.GENDER_FEMALE or SZRConstant.GENDER_MALE */
    .put(SZRConstant.YEAR_OF_BIRTH, <User Year of Birth>)

    // service related properties
    .put(SZRConstant.SERVICE_TYPE, "<Service Type>")
    .put(SZRConstant.SESSION_ID, "<Session ID>")
    .put(SZRConstant.STREAMING_SERVER_NAME, "<Streaming Server Name>")    /*Server name or source URL */
    .put(SZRConstant.ABTEST_MARK, "<AB Test Marking>")

    // platform related properties
    .put(SZRConstant.PLATFORM_NAME, "<Android>")
    .put(SZRConstant.APPLICATION_NAME, "<Streamlyzer Example Application>")
    .put(SZRConstant.APPLICATION_VERSION, "<0.9.x.0>")
    .put(SZRConstant.PLAYER_PLATFORM_VERSION, "<MediaPlayer>")
    .put(SZRConstant.MEDIA_PLAYER_VERSION, "<Streamlyzer Example VideoPlayer 0.9.x.0>")
);

Event API

countableEvent Description
postUserDefinedCountEvent Count Event is an event that you want to count the number of event. group: Group name of the event. cntEvtName : Count event name Previously it was “countableEvent”
postUserDefinedSumEvent Sum Event is an event that you want to sum sumProperty of event. group: Group name of the event. sumEvtName: The key name to be summed. sumValue: The value to be summed. This should be Number, not String. Previously it was “sumEvent”
postUserDefinedRevenueEvent Revenue Event is an event that you want to analyze revenue you make from individual users. By associating with users, you can analyze revenue across different user segment and calculate key business metrics such as lifetime value. group: Group name of the event revEvtName: The key name of Revenue type revValue: The value of Revenue. This should be Number, not String. Previously it was “revenueEvent”

Example


// trigger UserDefinedEvent
szrEvent.postUserDefinedCountEvent("EventGroupName", "CountName");

szrEvent.postUserDefinedSumEvent("EventGroupName", "SumEvent", <Sum Event Value>);

szrEvent.postUserDefinedRevenueEvent("EventGroupName", "RevenueEvent", <Revenue Event Value>);

pageReferrerObserver

Description

pageReferrerObserver analyzes your service traffic as well as in-site moving.

How to initialize

To initialize pageReferrerObserver, you should set up proper properties. you can initialize observer like:


// Initialize plug-in
SZRPlugin.initPlugin();

// Initialize PageReferrer Observer
SZRPageReferrerObserver szrEvent = new SZRPageReferrerObserver();
szrEvent.setContext(this);

// Set properties
szrEvent.setProperties(new JSONObject()
    // key provided by Streamlyzer
    .put(SZRConstant.CUSTOMER_KEY, "<Key Provided by Streamlyzer>")

    // end user related properties
    .put(SZRConstant.USER_ID, "<User ID>")
    .put(SZRConstant.USER_TYPE, "<User Type>")
    .put(SZRConstant.GENDER, "<User Gender>") /* SZRConstant.GENDER_FEMALE or SZRConstant.GENDER_MALE */
    .put(SZRConstant.YEAR_OF_BIRTH, <User Year of Birth>)

    // service related properties
    .put(SZRConstant.SERVICE_TYPE, "<Service Type>")
    .put(SZRConstant.SESSION_ID, "<Session ID>")
    .put(SZRConstant.STREAMING_SERVER_NAME, "<Streaming Server Name>")    /*Server name or source URL */
    .put(SZRConstant.ABTEST_MARK, "<AB Test Marking>")

    // platform related properties
    .put(SZRConstant.PLATFORM_NAME, "<Android>")
    .put(SZRConstant.APPLICATION_NAME, "<Streamlyzer Example Application>")
    .put(SZRConstant.APPLICATION_VERSION, "<0.9.x.0>")
    .put(SZRConstant.PLAYER_PLATFORM_VERSION, "<MediaPlayer>")
    .put(SZRConstant.MEDIA_PLAYER_VERSION, "<Streamlyzer Example VideoPlayer 0.9.x.0>")
);

Event API

Function Signiture Description
postPageReferrerEvent Count Event is an event that you want to count the number of event. referrerHostName : Referrer Host Name referrerPagePath : Referrer Page Path currentPagePath : Current Page Path

Example


// trigger pageReferrerEvent
szrEventpostPageReferrerEvent("<referrer host name>", "<referrer page path>", "<current page path>");

sharedContentObserver

Description

sharedContentObserver analyzes your service out-bound traffic.

How to initialize

To initialize sharedContentObserver, you should set up proper properties. you can initialize observer like:


/// Initialize plug-in
SZRPlugin.initPlugin();

// Initialize Shared Contents Observer
SZRSharedContentsObserver szrEvent = new SZRSharedContentsObserver();
szrEvent.setContext(this);

szrEvent.setProperties(new JSONObject()
    // key provided by Streamlyzer
    .put(SZRConstant.CUSTOMER_KEY, "<Key Provided by Streamlyzer>")

    // end user related properties
    .put(SZRConstant.USER_ID, "<User ID>")
    .put(SZRConstant.USER_TYPE, "<User Type>")
    .put(SZRConstant.GENDER, "<User Gender>") /* SZRConstant.GENDER_FEMALE or SZRConstant.GENDER_MALE */
    .put(SZRConstant.YEAR_OF_BIRTH, <User Year of Birth>)

    // service related properties
    .put(SZRConstant.SERVICE_TYPE, "<Service Type>")
    .put(SZRConstant.SESSION_ID, "<Session ID>")
    .put(SZRConstant.STREAMING_SERVER_NAME, "<Streaming Server Name>")    /*Server name or source URL */
    .put(SZRConstant.ABTEST_MARK, "<AB Test Marking>")

    // platform related properties
    .put(SZRConstant.PLATFORM_NAME, "<Android>")
    .put(SZRConstant.APPLICATION_NAME, "<Streamlyzer Example Application>")
    .put(SZRConstant.APPLICATION_VERSION, "<0.9.x.0>")
    .put(SZRConstant.PLAYER_PLATFORM_VERSION, "<MediaPlayer>")
    .put(SZRConstant.MEDIA_PLAYER_VERSION, "<Streamlyzer Example VideoPlayer 0.9.x.0>")

    // for play item
    .put(SZRConstant.BIT_RATE, 320)         /* bitrate in kbs */
    .put(SZRConstant.RESOLUTION, "720p")    /* resolution */
    .put(SZRConstant.LIVE_CHANNEL_NAME, "<Live Channel Name>")
    .put(SZRConstant.MOVIE_CATEGORY, "<Movie Category>")
};

Event API

Function Signiture Description
postSharedContentsEvent evtGroup: Group name of the event. destination: Shared Destination. with this property. you can send any string, however, we strongly recommend to use below list. Twitter: “twitter” Facebook: “facebook” Google+: “googleplus” Blogger:”blogger” Tumblr: “tumblr” reddit: “reddit” Pinterest: “pinterest” LiveJournal: “livejournal”

Example


// trigger SharedEvent
szrEvent.postSharedContentsEvent("EventGroupName", "twitter");


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s