Digiteka InStream Library

The Digiteka InStream library provides an interactive component for displaying floating video players in Android applications.

Table of Contents

• Installation
• Quick Start
• Configuration
• Implementation
  • XML Layout Implementation
  • Jetpack Compose Implementation
• Advanced Features
  • Custom Logger
  • Error Handling
• Demo Application

Installation

Add the following dependency to your module's build.gradle file:

dependencies {
    implementation("com.github.digiteka:SDK-instream-Android:1.1.0-0")
}

Quick Start

Initialize the library in your Application class's onCreate() method:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Create configuration
        val dtkisConfig = DTKISConfig.Builder(
            mdtk = "YOUR_MDTK_KEY"
        ).build()
        
        // Initialize the InStream library
        InStream.initialize(
            applicationContext = this.applicationContext,
            config = dtkisConfig
        )
    }
}

Configuration

DTKISConfig

Main configuration object for the InStream library.

Parameter	Type	Required	Description
mdtk	String	Yes	Your Digiteka API key

DTKISMainPlayerConfig

Configuration for the main video player component.

Parameter	Type	Required	Description
zone	String	Yes	Identifies the website zone where the video is published
src	String	Yes	Video ID to be played
urlreferrer	String	Yes	Desktop article URL (referrer URL)
gdprConsentString	String	No	User's GDPR consent string
tagParam	String	No	Optional advertising parameters
playMode	PlayMode	No	Video playback behavior (default: ON_CLICK)

PlayMode Options

• ON_CLICK: Video starts when user taps the player
• AUTOPLAY: Video starts automatically when loaded
• VISIBLE_AT_FIFTY_PERCENT: Video starts when 50% visible in viewport

DTKISVisiblePlayerConfig

Configuration for the floating visible player (optional component).

Parameter	Type	Required	Description
playerPosition	Position	Yes	Player position on screen
widthPercent	Float	Yes	Player width as percentage of parent view (0.0-1.0)
ratio	String	Yes	Aspect ratio (e.g., "16:9")
horizontalMargin	Float	Yes	Horizontal margin in dp
verticalMargin	Float	Yes	Vertical margin in dp

Position Options

• TOP_START: Top-left corner
• TOP_END: Top-right corner
• BOTTOM_START: Bottom-left corner
• BOTTOM_END: Bottom-right corner

Implementation

XML Layout Implementation

Step 1: Add MainPlayerView to Layout

<com.digiteka.instream.ui.player.MainPlayerView
    android:id="@+id/main_player"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    app:layout_constraintDimensionRatio="16:9"
    app:layout_constraintTop_toBottomOf="@id/content"
    tools:ignore="WebViewLayout" />

Step 2: Configure MainPlayerView

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        val mainPlayerConfig = DTKISMainPlayerConfig.Builder(
            zone = "11",
            gdprConsentString = "your_consent_string",
            src = "video_id",
            urlReferrer = "https://your-website.com/article",
            tagParam = null
        ).setPlayMode(PlayMode.VISIBLE_AT_FIFTY_PERCENT).build()

        val mainPlayerKey = InStream.configureMainPlayer(
            binding.mainPlayer,
            mainPlayerConfig
        )
    }
}

Step 3: Add Visible Player (Optional)

The visible player is an optional floating component that appears when the main player scrolls out of view. If attachVisiblePlayerTo is not called, the MainPlayerView will continue playing without pausing when it goes off-screen.

// Optional: Add floating visible player
InStream.attachVisiblePlayerTo(
    parent = binding.root,
    visiblePlayerConfig = DTKISVisiblePlayerConfig(
        widthPercent = 0.66f,
        position = Position.BOTTOM_START,
        ratio = "16:9",
        horizontalMargin = 8f,
        verticalMargin = 8f
    ),
    mainPlayerKey = mainPlayerKey
)

Jetpack Compose Implementation

Step 1: Configure Main Player

@Composable
fun VideoScreen() {
    val mainPlayerConfig = DTKISMainPlayerConfig.Builder(
        zone = "11",
        gdprConsentString = "your_consent_string",
        src = "video_id",
        urlReferrer = "https://your-website.com/article",
        tagParam = null
    ).setPlayMode(PlayMode.VISIBLE_AT_FIFTY_PERCENT).build()
    
    val mainPlayerView = remember { MainPlayerView(LocalContext.current) }
    val mainPlayerKey = remember {
        InStream.configureMainPlayer(mainPlayerView, mainPlayerConfig)
    }
    
    MainPlayerComposable(mainPlayerView = mainPlayerView)
}

Step 2: Add Visible Player (Optional)

@Composable
fun App() {
    MaterialTheme {
        Surface {
            Box {
                VideoScreen()
            }
        }
        
        // Optional: Add floating visible player
        // If not called, MainPlayerView will not pause when off-screen
        InStream.attachVisiblePlayerTo(
            parent = findViewById(android.R.id.content),
            visiblePlayerConfig = DTKISVisiblePlayerConfig(
                widthPercent = 0.66f,
                position = Position.BOTTOM_START,
                ratio = "16:9",
                horizontalMargin = 8f,
                verticalMargin = 8f
            ),
            mainPlayerKey = mainPlayerKey
        )
    }
}

Advanced Features

Custom Logger

Implement a custom logger to capture library logs by implementing the DTKISLogger interface:

import android.util.Log
import com.digiteka.instream.core.log.DTKISLogger

object CustomLogger : DTKISLogger {
    private const val TAG = "DigitekaInStream"
    
    override fun debug(message: String) {
        Log.d(TAG, message)
    }
    
    override fun info(message: String) {
        Log.i(TAG, message)
    }
    
    override fun warning(message: String, throwable: Throwable?) {
        Log.w(TAG, message, throwable)
    }
    
    override fun error(message: String, throwable: Throwable?) {
        Log.e(TAG, message, throwable)
    }
}

Register your custom logger:

InStream.setLogger(logger = CustomLogger)

Error Handling

The library provides structured error codes and logging:

Type	Error Code	Level	Description	Cause
Configuration	DTKIS_CONF_1	Critical	Invalid API key	mdtk is null, empty, or blank
Configuration	DTKIS_CONF_2	Error	No configuration data	Empty data array or no zone contains video
Configuration	DTKIS_CONF_3	Error	Library not initialized	InStream.initialize() not called
Configuration	DTKIS_CONF_4	Error	Invalid URL format	Malformed urlReferrer URL
SDK	DTKIS_SDK_1	Critical	Unknown player	Invalid player ID provided

Demo Application

Test the library using the demo application with the provided test key:

1. Add the following to your project's local.properties file:

   DIGITEKA_INSTREAM_MDTK=01357940
   DIGITEKA_VIDEOFEED_SECRET=your_digiteka_jitpack_auth_token_here
   

2. Build and run the demo application to see the library in action.