Ease Live

Appearance

Migration ​

2.17.0 ​

Deprecated use of LocalBroadcastListener ​

Use of LocalBroadcastListener will be removed in a future version.

App should be changed to listen for events from SDK and overlay using easeLive.on, and for sending events to the overlay using easeLive.emit.

See Events for a list of events. See Example project for updated example using the new methods.

Sending events from app to overlay ​

Old implementation ​
kotlin
val jsonObject = JSONObject()
jsonObject.put("event", "myPrefix.myEvent")
val metadata = JSONObject()
metadata.put("myCustomValue", "some data")
jsonObject.put("metadata", metadata)

val broadcast = Intent(EaseLiveNotificationKeys.APP_MESSAGE)
broadcast.putExtra(EaseLiveNotificationKeys.EXTRA_JSON_STRING, jsonObject.toString())
LocalBroadcastManager.getInstance(this).sendBroadcast(broadcast)
New implementation ​
kotlin
val eventName = "myPrefix.myEvent"
val metadata = JSONObject()
metadata.put("myCustomValue", "some data")
easeLive.emit(EaseLiveEvent.MessageEvent(eventName, metadata))

Listening for events from SDK and overlay ​

Change use of LocalBroadcastManager and BroadcastReceiver that listens for event defined by names in EaseLiveNotificationKeys to adding listeners for events defined in EaseLiveEvent using method easeLive.on .

Old implementation ​

using deprecated broadcast receiver

kotlin
val easeLiveBroadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        when (intent.action) {
            EaseLiveNotificationKeys.EASE_LIVE_READY -> {

                // the overlay UI loaded successfully
                Log.d(TAG, "onReceive: " + EaseLiveNotificationKeys.EASE_LIVE_READY)
            }

            EaseLiveNotificationKeys.EASE_LIVE_ERROR -> {

                // an error occurred
                Log.d(TAG, "onReceive: " + EaseLiveNotificationKeys.EASE_LIVE_ERROR)
                intent.getParcelableExtra<Error>(EaseLiveNotificationKeys.EXTRA_ERROR)
                    ?.let { error ->
                        if (error.level == Error.LEVEL_FATAL) {
                            // fatal error. For example the UI failed to load.
                            // remove the overlay and fallback to a normal video
                            easeLive?.destroy()
                            easeLive = null
                        } else {
                            // non-fatal error/warning.
                        }
                    }
            }

            EaseLiveNotificationKeys.BRIDGE_APP_STATUS -> {
                // notification that the producer changed status of the loaded overlay.
                // When the overlay was disabled, it should be removed
                if ("disabled" == intent.getStringExtra(EaseLiveNotificationKeys.EXTRA_STATUS)) {
                    easeLive?.destroy()
                    easeLive = null
                }
            }

            EaseLiveNotificationKeys.BRIDGE_MESSAGE -> {
                // custom message from the overlay UI

                try {
                    val jsonString =
                        intent.getStringExtra(EaseLiveNotificationKeys.EXTRA_JSON_STRING)
                    if (jsonString != null) {
                        val jsonObject = JSONObject(jsonString)
                        val eventName = jsonObject.getString("event")

                        // example of a message used for sharing a Watch Party invitation
                        if ("inviteMessage" == eventName && jsonObject.has("metadata")) {
                            val metadata = jsonObject.getJSONObject("metadata")
                            val message = metadata.getString("message")

                            if (!message.isNullOrEmpty()) {
                                val sendIntent: Intent = Intent().apply {
                                    action = Intent.ACTION_SEND
                                    putExtra(Intent.EXTRA_TEXT, message)
                                    type = "text/plain"
                                }

                                val shareIntent = Intent.createChooser(sendIntent, null)
                                startActivity(shareIntent)
                            }
                        }
                    }

                } catch (e: JSONException) {

                }
            }

            EaseLiveNotificationKeys.VIEW_CREATED -> {
                // only use if using Google Mobile Ads SDK
                // EaseLive has created a webview. Register it with the Google ads instance
                (easeLive?.viewPlugin?.view as? ExtendedWebView)?.let { webView ->
                    MobileAds.registerWebView(webView)
                }
            }
        }
    }
}
val filter = EaseLive.getIntentFilter()
filter.addAction(EaseLiveNotificationKeys.VIEW_CREATED)
LocalBroadcastManager.getInstance(this)
    .registerReceiver(easeLiveBroadcastReceiver, filter)
New implementation ​

using new event listener

kotlin
easeLive.on<EaseLiveEvent.ReadyEvent> {
    // the overlay UI loaded successfully
    Log.d(TAG, "EL ready")
}

easeLive.on<EaseLiveEvent.ErrorEvent> { e ->
    Log.d(TAG, "EL error " + e.error)
    if (e.error.level == Error.LEVEL_FATAL) {
        // fatal error. For example the UI failed to load.
        // remove the overlay and fallback to a normal video
        easeLive?.destroy()
        easeLive = null
    } else {
        // non-fatal error/warning.
    }
}

easeLive.on<EaseLiveEvent.StatusEvent> { e ->
    Log.d(TAG, "EL status " + e.status)
    // notification that the producer changed status of the loaded overlay.

    if (e.status == Status.DISABLED) {
        // When the overlay was disabled, it should be removed
        easeLive?.destroy()
        easeLive = null
    } else if (e.status == Status.HIDDEN) {
        // overlay temporarily hidden
    } else if (e.status == Status.ENABLED) {
        // overlay is enabled
    }
}

easeLive.on<EaseLiveEvent.ViewCreatedEvent> { e ->
    // view was created in EaseLive

    // only use if using Google Mobile Ads SDK
    // EaseLive has created a webview. Register it with the Google Ads instance
    (easeLive?.viewPlugin?.view as? ExtendedWebView)?.let { webView ->
        MobileAds.registerWebView(webView)
    }
}

easeLive.on<EaseLiveEvent.MessageEvent> { e ->
    // receiving a custom message from the overlay UI

    // example of a message used for sharing a Watch Party invitation
    if ("inviteMessage" == e.event) {
        val message = e.metadata.getString("message")

        if (!message.isNullOrEmpty()) {
            val sendIntent: Intent = Intent().apply {
                action = Intent.ACTION_SEND
                putExtra(Intent.EXTRA_TEXT, message)
                type = "text/plain"
            }

            val shareIntent = Intent.createChooser(sendIntent, null)
            startActivity(shareIntent)
        }
    }
}

Changed SDK implementation to Kotlin ​

If the app uses Kotlin there should be no changes related to this.

If the app uses Java:

default access modifiers for all PlayerPluginBase changed to public Before:

protected void setControllerVisible(boolean visible)
protected void setTime(long time)
protected void setState(@NonNull PlayerState state)

After:

public void setControllerVisible(boolean visible)
public void setTime(long time)
public void setState(@NonNull PlayerState state)

2.15.0 ​

Widget plugin implementation changes signature of show() to show(FrameLayout, WidgetData) and hide() to hide(FrameLayout, WidgetData).

2.12.0 ​

Deprecated old constructor for loading overlay by URL. Instead use constructor taking accountId and programId.

Deprecated old method setWebUrl for changing program by URL. Instead use setProgram.

2.11.0 ​

Preferred repository URL changed from https://ease-live-sdk-releases.s3.eu-central-1.amazonaws.com/maven to https://sdk.easelive.tv/maven:

repositories {
    maven {
        url "https://sdk.easelive.tv/maven"
    }
}

2.10.0 ​

Removed the old package name deprecated since version 2.5.0.

Set minSdkVersion 21. If app targets minSdkVersion 20 or lower conditionally load SDK

2.9.1 ​

Previous versions would enable debugging of the contents of the web-based overlay while running a debug build of an app that had set EaseLive.setDebugging(BuildConfig.DEBUG) . This would call WebView.setWebContentsDebuggingEnabled to true in debug builds and false in release builds.

In this version it's been removed, because some static analysis tools will flag any call of setWebContentsDebuggingEnabled as a security risk, even when it is set to false to disable debugging. If required to debug the overlay contents, WebView.setWebContentsDebuggingEnabled(true) can be called by your app before creating the EaseLive instance, and should be done only while debugging.

2.5.0 ​

Maven package moved ​

Change the repository URL to

repositories {
    maven {
        url "https://ease-live-sdk-releases.s3.eu-central-1.amazonaws.com/maven"
    }
}

and change the dependency to

dependencies {
    implementation 'tv.easelive:easelivesdk:2.5.0'
}

Deprecated old package name no.sixty.ease_live_bridge ​

Change all imports from import no.sixty.ease_live_bridge.* to import tv.easelive.easelivesdk.*

2.2.x → 2.3.0 ​

Deprecated EaseLivePlayerStates ​

The state constants in the class EaseLivePlayerStates is replaced by enum PlayerState.

PlayerPluginBase subclasses should change:

  • overrides of setState(@NonNull String state) should be changed to setState(@NonNull PlayerState state)
  • calls to onState(@NonNull String state) should be changed to onState(@NonNull PlayerState state)

Removed interfaces methods ​

Interface methods that were not necessary have been removed. Classes implementing the interfaces can keep the methods, but must remove the @Override annotation for the removed interface methods. This applies to:

  • Plugins implementing interface ComponentInterface.
  • Player plugins implementing interface PlayerPluginInterface directly without extending PlayerPluginBase.

2.1.0 → 2.2.0 ​

PlayerPlugin: Changed timecode datatype from String to long ​

  • in player plugin setTime(String time) should be changed to setTime(long time)
  • in player plugin onTime(String time) should be changed to onTime(long time)
  • Receivers of EaseLiveNotificationKeys.BRIDGE_TIME event should read the timecode extra as long: intent.getLongExtra(EaseLiveNotificationKeys.EXTRA_TIMECODE)

Copyright © Ease Live AS