SDK for Android

v.1.4.0
Primis Android SDK latest version is 1.4.0, Download from here.

Apps built with the Primis Player SDK for Android will obtain a fully working Primis player with most of its web functionalities.

Key Supported Features:

  • Skins
  • Layouts
  • Playlists
  • Monetization
  • Floating mode
  • Viewability detection

Requirements

Item

Notes

Android Studio

IDE for Android

Android SDK version

The minimum Android SDK version is 5.0 (API level 21)

Primis placement ID

Reach out to your Pub. Success Manager at Primis for more details

Primis SDK

Latest version 1.4.0, Download from here

Google IMA SDK for Android

Version 3.22.3, Implementation steps below

Basic Terms

A few terms to be familiar with before we start:

Primis player - A Web-based video player running inside a WebView
Primis SDK - An Android library providing essential native functionality
Floating unit/mode - A floating Primis player that can be located on the screen according to placement settings
Player container - A FrameLayout that is used as Primis player view container when it is not in floating mode
Flow parent - The view group of type FrameLayout to be used as the floating player container
Placement ID - A unique identifier for the player set of settings predefined in the Primis dashboard

General Installation

We recommend using Gradle for the integration.
Primis monetization services require Google IMA SDK.
Please follow the guidelines below for successful integration.

Gradle setup and importing

  1. Add Primis AAR file (primisplayer-release-vX.X.X.aar) to "Project-Name/app/libs" folder.
  1. Add the following code to "Project-Name/build.gradle":
allprojects {
 repositories {
  google()
  jcenter()

  flatDir {
   dirs 'libs'
  }
 }
}
  1. Add the following code to "Project-Name/app/build.gradle" under “dependencies”:
dependencies {
 ....


 // Primis player SDK, replace X.X.X with the current SDK version
 implementation 'primis.tech:primisplayer-release:[email protected]'


 //Support for JSON
 implementation 'com.google.code.gson:gson:2.8.6'

 //Support for DIAID (ad ID)
 implementation 'com.google.android.gms:play-services-ads:20.0.0'


 // Support for Google IMA SDK
 implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.22.3'

 ....


}
  1. In the gradle.properties file, set “android.useAndroidX” and “android.enableJetifier” to true. These plugin files enable you to use androidx-namespaced libraries in your project. If you are using a current version of Android Studio, the gradle.properties file should already contain these settings.

  2. If you are using proguard to build your app, add the following rule:

-keep class tech.primis.player** {*;}
  1. To import Primis player add the following:
import tech.primis.player.PrimisPlayer

Prepare a floating container
Depending on your placement configuration, when the user scrolls the player off the screen, the player will switch to floating mode.
In this section, you will be asked to provide a floating container view group as FrameLayout which will be used to contain the player in its’ floating mode.

The floating container must be provided, even if the placement currently does not support enabling floating mode.

  1. Create the floating container object as FrameLayout.
val floatingContainer: FrameLayout = FrameLayout(applicationContext)
  1. Create a FrameLayout.LayoutParams object and assign it to the floating container.
val flp = FrameLayout.LayoutParams(
 FrameLayout.LayoutParams.MATCH_PARENT,
 FrameLayout.LayoutParams.MATCH_PARENT
)

floatingContainer.layoutParams = flp
  1. Add the floating container to the main view layout.
mainViewLayout.addView(floatingContainer)
  • The settings of the flow parent can be made in the XML file as well.
  • We used ConstraintLayout as the main ViewGroup but you can use any ViewGroup you like.

Adding Primis player

  1. Create a Primis player variable. This view contains the Primis player and all of its functionality. The PrimisPlayer class is an extension of “FrameLayout” and therefore may be added to any ViewGroup type.
    Please note that we support the creation of exactly one Primis player per view.
var primisPlayer: PrimisPlayer = PrimisPlayer(applicationContext)
  1. Create Primis configuration list object and add the following. “placementId” and “flowParent” are mandatories. The list is of type Listspan <PrimisPlayer.param>(). Each param contains “id” and “value”.
var config = listOf(

 // The placement ID
 PrimisPlayer.param("placementId", "123456")

 // The flow container
 , PrimisPlayer.param("flowParent", primisFlowContainer)
)
  1. Set the config object to PrimisPlayer.
primisPlayer.setConfig(config)

Implementation type

According to your implementation type, please continue to one of the two sections below:

  • RecyclerView Implementation
  • ScrollView Implementation

RecyclerView Implementation

Adding the Primis Player to a RecyclerView.

  1. Add a PrimisPlayer property to the RecyclerView.Adapter.
class RecyclerViewAdapter(
....
) : RecyclerView.Adapter() {

....

 private var player: PrimisPlayer? = null

....

}
  1. Override ‘onAttachedToRecyclerView’ method of the RecyclerView.Adapter and set the Primis player configuration object as described in the previous section.
    One of the configuration parameters must be isInRecyclerView where you should pass the RecyclerView object.

  2. Make sure to call ‘onAdapterAttachedToRecyclerView’ of PrimisPlayer after step 2:

override fun onAttachedToRecyclerView(recyclerView: RecyclerView) {
 super.onAttachedToRecyclerView(recyclerView)

 ....

 val mainBinding = DataBindingUtil.findBinding(recyclerView)
  val primisFlowContainer = mainBinding.floatingContainer

 if (player == null) {
  player = PrimisPlayer(applicationContext)

  val config = listOf(

   // The placement ID
   PrimisPlayer.param("placementId", "123456"),


   // The flow container
   PrimisPlayer.param("flowParent", primisFlowContainer)

   // Use this only if implementing the player in RecyclerView
   PrimisPlayer.param("isInRecyclerView", recyclerView)
  )

  player.setConfig(config)
 }

 // This call is important since it notifies PrimisPlayer that the adapter attached
 // to RecyclerView.
 player?.onAdapterAttachedToRecyclerView()

 ....
}

If not using DataBinding, holder.itemView.findViewById<>() can be used to get a reference and send to the player container from the ViewHolder.

  1. Override ‘onAttachedToWindow’ method of the RecyclerView.Adapter, get a reference to player container view inside the ViewHolder item and send it to the player through method ‘onAttachedToRecyclerView’. This will notify the PrimisPlayer that the designated cell is attached to window and it can be added to its container:
override fun onViewAttachedToWindow(holder: RecyclerViewItemHolder) {
 super.onViewAttachedToWindow(holder)

 ....

 if (holder.itemViewType == VIEW_TYPE_PLAYER) {
  player?.let {

   // Get a reference to the player container view in the player cell.
   val playerContainer = DataBindingUtil
    .findBinding(holder.itemView)?.
    playerContainer

   // Send the player container view to the player.
   it.onAttachedToRecyclerView(playerContainer)
  }
 }

 ....

}

The above implementation uses itemViewType. This can also be done by using ViewHolder.adapterPosition when it equals the player’s ViewHolder item position.

  1. Override ‘onViewDetachedFromWindow’ method of the RecyclerView.Adapter to notify the player through method ‘onDetachedFromRecyclerView’ that it is no longer attached to RecyclerView:
override fun onViewDetachedFromWindow(holder: RecyclerViewItemHolder) {
 super.onViewDetachedFromWindow(holder)

 ....

 if (holder.itemViewType == VIEW_TYPE_PLAYER) {
  player?.let {
   it.onDetachedFromRecyclerView()
  }
 }

 ....

}
  1. Make sure to call these PrimisPlayer methods only from inside of the respectively RecyclerView.Adapter native methods:
  • Call ‘onAdapterAttachedToRecyclerView’ from ‘onAttachedToRecyclerView’
  • Call ‘onAttachedToRecyclerView(playerContainer)’ from ‘onViewAttachedToWindow’
  • Call ‘onDetachedFromRecyclerView’ from ‘onViewDetachedFromWindow’
  1. In order to complete the RecyclerView integration, make sure to implement the RecyclerView related code mentioned in the Player destruction section.

Code example
You can find a code example for implementing the Primis player in RecyclerView here

ScrollView Implementation

Adding the Primis Player to a ScrollView.

  1. Get a reference to the view that will contain the Primis player (note that this ViewGroup is not the floating container):
val playerContainer = viewBinding.playerContainer
  1. Get a reference to the view that will contain the floating unit of Primis player:
val primisFlowContainer = viewBinding.floatingContainer
  1. Create a Primis player variable. This view contains the Primis player and all of its functionality. The PrimisPlayer class is an extension of “FrameLayout” and therefore may be added to any ViewGroup type.
val primisPlayer: PrimisPlayer = PrimisPlayer(applicationContext)
  1. Set the Primis player configuration object as mentioned in a previous section.
var config = listOf(

 // The placement ID
 PrimisPlayer.param("placementId", "104121")

 // The flow container
 , PrimisPlayer.param("flowParent", primisFlowContainer)
)
  1. Set the config object to Primis player:
primisPlayer.setConfig(config)
  1. Attach Primis player to its container:
playerContainer.addView(primisPlayer)

We used ViewBinding in our example but other approaches are good as well.

Code example

package com.app.example-app

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.FrameLayout
import androidx.constraintlayout.widget.ConstraintLayout

// Primis pack
import tech.primis.player.PrimisPlayer

class Screen : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_screen)

//Fetch the top layout (can be constraintLayout) view by its ID as declared in the app
  val topScreenLayout = findViewById(R.id.screenConstraintLayout)

//Create a flow-container (Must be of type "FrameLayout") for the player where it will be located once it goes on flow mode.
  val primisFlowContainer: FrameLayout = FrameLayout(applicationContext)

//Set the flow-container layout params to stretch on the entire screen
  val flp = FrameLayout.LayoutParams(
    rameLayout.LayoutParams.MATCH_PARENT,
    FrameLayout.LayoutParams.MATCH_PARENT)
  primisFlowContainer.layoutParams = flp

//Add the flow-container to the top constraint layout
  topScreenLayout.addView(primisFlowContainer)

//Create a Primis player. This view contains the primis player and all of its functionality.
//The PrimisPlayer class is an extension of "FrameLayout" and therefore may be added to any view type.
  var primisPlayer: PrimisPlayer = PrimisPlayer(applicationContext)

//Set configurations for the Primis player
  var config = listOf(
    PrimisPlayer.param("placementId", "123456"), //The placement ID
    PrimisPlayer.param("flowParent", primisFlowContainer) //The flow container
  )

//Add configurations to the Primis player
  primisPlayer.setConfig(config)

//Fetch the view that will contain the Primis player.
  val playerContainer = findViewById(R.id.ViewContainer)

//Add Primis player to its container. Once added it will initiate.
  playerContainer.addView(primisPlayer)
  }
}

Player Destruction

We highly recommend that you will stop the player’s activity on a page when the View is about to be destroyed (e.g. onDestroy(), onDestroyView()).

The destruction of the player is handled internally in the SDK when the player is detached from view.

//PlayerContainer is referred to the container where the PrimisPlayer was added to.
playerContainer.removeView(primisPlayer)

In RecyclerView call removeView(view) from onDetachedFromRecyclerView(recyclerView: RecyclerView):

override fun onDetachedFromRecyclerView(recyclerView: RecyclerView) {
 super.onDetachedFromRecyclerView(recyclerView)

 ....

 primisPlayer?.let {
   (it.parent as? ViewGroup)?.removeView(it)
 }

 ....

}

Advanced Features

Consent management
Primis Player supports consent strings in IAB TCF format, version 2. If your app uses certified IAB CMP, the SDK will read the consent string from SharedPreferences according to the standard.

Otherwise, to start the Player with some pre-defined consent string, pass it in the configuration object by defining “consent” and “consentVersion” parameters:

var config = listOf(


 ....

 // consent string only if CMP is not installed
 PrimisPlayer.param("consent", consentString),

 // consent string version
 PrimisPlayer.param(“consentVersion”, ”2”)
)

Friendly View Registration
Primis player automatically detects when a view is overlapping the player and as a result, the player stops.

If needed, the host application can register friendly views with unique ids (of type int) to be ignored by the overlapping feature.

Please consult with the Primis team before using this feature.

Steps:

  1. Add a unique id/s to ids.xml file or set the id in the XML layout:
<item name="some_unique_id" type="id" />

or

android:id="@+id/some_unique_id"
  1. Create HashSet and add all of the ids needed as friendly views.
    In the case of multiple views inside a ViewGroup, only the ViewGroup’s id is needed.
val set = hashSetOf<Int>()
set.add(R.id.some_view_id)
set.add(R.id.some_another_view_id)
....
  1. Add the friendly views Set to Primis player config with the “friendlyViewIdsList” key:
var config = listOf(
 ....
 PrimisPlayer.param("friendlyViewIdsList", set),
 ....
)

Did this page help you?