Android SDK Advanced Features

Floating Player Preset

Based on your placement configuration, when the user scrolls the player off the screen, the player will switch to floating mode.

If you need an advanced control (e.g., the place of the flowParentView in the view tree hierarchy, dimensions etc.) you will need to follow this section and provide a floating container view group as FrameLayout, which will be used to contain the player in its floating mode.

Create the floating container object as FrameLayout.

val floatingContainer: FrameLayout = FrameLayout(applicationContext)

Create a FrameLayout.LayoutParams object and assign it to the floating container. It is highly recommended that you will keep these parameters for best performance and UX.

val flp = FrameLayout.LayoutParams(
    FrameLayout.LayoutParams.MATCH_PARENT,
    FrameLayout.LayoutParams.MATCH_PARENT
)

floatingContainer.layoutParams = flp

Add the floating container to the main view layout.

mainViewLayout.addView(floatingContainer)

Add the floating parent view by passing it to the PrimisConfiguration.Builder’s floatingPlayerContainer() function:

primisPlayer = PrimisConfiguration.Builder()
			...
			.floatingPlayerContainer(floatingContainer)
			...

If floating will be activated in the dashboard, but the floating container won’t be set by the host application, PrimisPlayer will set a default one.
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.

One Player – multiple indexes in RecyclerView

PrimisPlayer can be shown in (more than one) different indexes during scrolling in RecyclerView.
In our example, we override getItemViewType(position: Int) and set to which of the cells the player will be added.

No need to instantiate the player more than once, just override getItemViewType(position: Int) and set the requested indexes.

override fun getItemViewType(position: Int): Int {
    return if (position == FIRST_INDEX || position == SECOND_INDEX || ...) {
        VIEW_TYPE_PLAYER
    } else {
        ...
    }
}

The player must be added to a recycled cells which means only one player will be shown on screen at a time.
Note: Do not set a floating player in the placement configuration (in Primis dashboard) if using this mode, since enabling it in this mode may result in unexpected behavior.

Player API

Primis SDK allows the host application to register and start listening to events that are triggered inside the video player (e.g., when video content starts playing or when the user clicks on an ad).

A full list of available player API events can be found here.

Implement PrimisPlayerEventListener:

class YourPrimisPlayerEventListener: PrimisPlayerEventListener {
    override fun onPrimisPlayerApiEvent(event: PlayerApiEvent) {
        // Here you'll be able to extract the event's data
        ...
        when(event.eventType) {
            "videoEnd" - > {
                // This event doesn’t include a value
            }

            "volumeChange" - > {
                val newValue = event.data["singleValue"] as Double
            }

            "adStarted" - > {
                val impValue = event.data["impValue"] as Double
                val servingFee = event.data["servingFee"] as Double
            }

            "videoStart" - > {
                val title = event.data["title"] as String
                val duration = event.data["duration"] as String
            }
            ...
        }
    }
}

Set your event listener object to Primis player with the PrimisConfiguration.Builder’s eventListener() function

lateinit var primisPlayerEventListener: YourPrimisPlayerEventListener

...
	primisPlayerEventListener = YourPrimisPlayerEventListener()
	primisPlayer = PrimisConfiguration.Builder()
			...
			.eventListener(primisPlayerEventListener)
			...

📘
The Player API callback calls are made on a background thread.

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:

If using a native (Mobile) consent, then, the SDK will address SharedPreferences according to the standard.
If using a Web consent (inside the webView) , the SDK will address the __tcfapi() according to the standard.

To set a web consent in WebView implementation (this step is not required for native consent):

// Initialize the PrimisPlayer here
primisPlayer = PrimisConfiguration.Builder()
    	.placement("123456")// The placement ID
			....
			.hostAppConsentType(Consent.Type.WEB_CONSENT)
			....

To start the Player with some pre-defined consent string, pass it to the PrimisConfiguration.Builder object using the consent() function

primisPlayer = PrimisConfiguration.Builder()
...
.consent(consentString, "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:

Add a unique id/s to ids.xml file OR set the id in the XML layout:

<item name="some_unique_id" type="id" />

android:id="@+id/some_unique_id"

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

Add the friendly views Set to PrimisConfiguration.Builder with the friendlyViews() function:

primisPlayer = PrimisConfiguration.Builder()
			...
			.friendlyViews(set)
			...

Landscape Support

Primis player supports landscape orientation.
If your application supports landscape you need to set the following in the manifest.xml for better UX and monetization performance:

<activity android:name=".YourPlayerActivity"
    android:screenOrientation="sensor"
    android:configChanges="orientation|screenLayout|screenSize">

</activity>

By adding the above the onCreate() method won’t be called after screen rotation.

Additional Parameters

There are additional configuration parameters for the player. You may add the parameters, that will be set via the PrimisConfiguration.Builder’s additionalParams() function:

primisPlayer = PrimisConfiguration.Builder()
			...
			.additionalParams("vp_template=xxxx&cbuster=xxxx")
			...

The full list of available dynamic parameters can be found here.

Error Listener

In case of an error, where Primis player won’t be able to load, an “illegalPlacementEvent” will be fired via the PrimisPlayerErrorListener.onError(error: String).

In order to register to this event and get notified call setErrorListener() after instantiating PrimisPlayer like so:

primisPlayer.setErrorListener(object : PrimisPlayerErrorListener {
    override fun onError(error: String) {
        // TODO: Implement your code here...

    }
})

📘
Note

The error event is being fired on the main thread

Your view manager (e.g.: Activity or Fragment) can instead implement the PrimisPlayerErrorListener and override its member function ‘onError()’

Floating Player Preset

One Player – multiple indexes in RecyclerView

Player API

📘

Consent management

Friendly View Registration

Landscape Support

Additional Parameters

Error Listener

📘Note

📘
Note