AMP Player wrapper integration

The following document guides you through the steps of the AMP Android SDK Wrapper integration into your app. By the end of it, you will be able to play back an online video stream.

Introduction

You can integrate AMP into your app in two ways:

  1. AmpPlayer module: a "plug-and-play" wrapper to quickly get playback, UI, Close Captions, ads, and analytics "out of the box". This module implies fewer customizations and uses a default UI. This document will delve into this option.

  2. AMP Basic Integration: allows you to implement more complex use cases by leveraging AMP’s API. This integration requires more code development and provides more freedom.

Reach out to us at amp-sdk-support@akamai.com with any questions or concerns.

Integration

This guide follows the AmpPlayerSample Android Studio project, found in our release page.

To integrate AMP into your app, you need to:

1) Add the INTERNET permission to your AndroidManifest.xml:

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

2) The mandatory .jars and .aars you’ll need can be found in the AmpPlayerSample/libs folder; copy them to your app’s /libs folder:

  • amp-player.aar

  • amp-core.jar

  • amp-ui-mobile-generic.aar

  • amp-closed-captions.jar

3) Add the com.akamai.amp.AmpPlayer View to the desired Activity's XML layout:

    <com.akamai.amp.AmpPlayer
        android:id="@+id/amp"
        android:layout_width="match_parent"
        android:layout_weight="0.4"
        android:layout_height="0dp"
        android:background="@android:color/black" />

4) Add the com.akamai.amp.AmpPlayer to the Activity's Java code:

  • Add the import: import com.akamai.amp.AmpPlayer;

  • Declare the class’s attribute: private AmpPlayer amp;

  • Instantiate AMP’s main class, as you would do with any other UI component in your Activity or Fragment.

5) At this point, AMP is ready to be used. A quick test you could run is to play back a stream (the second parameter is the Activity being used):

    amp.play(STREAM_URL, this, AMP_LICENSE);

6) The previous step shows how to start a video with no UI to test whether the decoding works as expected. Let’s configure the AmpPlayer instance to take advantage of the rest of functionalities:

  • Call configure() with AMP’s API key, the activity reference, and an IMediaPlayerControllerListener callback:

    amp.configure( AMP_API_KEY, this, customButtonCallback() );

  • Call configureVisually() with the initial state of the UI, the controls, rotation and mini-player mode:

    /*
    Parameter 1: defines the initial player overlay state
    State.INLINE_PLAYER or State.FULLSCREEN_PLAYER

    Parameter 2: initial Controls mode
    Mode.INLINE, Mode.EMBEDDED or Mode.CONTENT_LIST

    Parameter 3: determines if the player must rotate when the device's orientation changes

    Parameter 4: determines if the player must start on mini-player mode
    */
    amp.configureVisually(State.INLINE_PLAYER, Mode.INLINE, true, true);

7) Prepare resource Builder: a media source can be prepared in different ways. The simplest one is playback. Other factors could be involved, such as video with CSAI, video with SSAI, 360 rendering, starting playback at a specific position, muted, paused, and others. For each one of those cases, this is how you should start the playback:

    amp.prepare().withStream(STREAM_URL).init();

The prepare() action is mandatory. Then, select the video you want to play. Check all the different playback options from the following list. Once those are set, call the init() action to continue.

        // Basic action to provide a stream URL
        withStream(String streamURL)

        // Sets the stream playlist extension manually
        withExtension(String extension)

        // Sets the stream mime type manually
        withMimeType(String mimeType)

        // Sets a starting point for non Live streams
        atPosition(int startPosition)

        // Sets a duration, in case it needs to get provided manually
        withDuration(int durationInSeconds)

        // enables thumbnails slider for VOD, receives the VTT source URL as parameter
        withThumbnails(String vtt)

        // enables thumbnails slider for VOD, receives the VTT source URL as parameter and the base path (in case the paths in the VTT file are relative)
        withThumbnails(String vtt, String basePath)

        // Defines if the video must autoplay or not upon start
        shouldPauseAtStart(boolean shouldPause)

        // Sets the video type (Live or non Live) in case it needs to be provided manually
        isLive(boolean isLive)

        // Sets the assetKey for Server Side Ads from Google, this represents the stream as well, passing an asset key eliminates the need to provide a stream URL
        withDAILive(String assetKey)

         // Sets the content source ID and Video Id for Server Side Ads from Google, for VOD, this represents the stream as well, passing these values eliminates the need to provide a stream URL
        withDAIVOD(String vodContentSourcedId, String videoId)

        // Sets the Ad Tag URL for Client Side Ads from Google, in case the IMA plugin has been properly configured before
        withClientSideIMA(String adsUrl)

        // Sets the manifest suffix in case it is required to attach anything to the URL requests for DAI
        withManifestSuffix(String manifestSuffix)

        // It initializes the playback using an internal proxy when Yospace Ads are properly configured before, similar to DAI, calling this method eliminates the need to provide a Stream URL
        withYospaceProxy()

       // It initializes the playback using the session approach when Yospace Ads are properly configured before, similar to DAI, calling this method eliminates the need to provide a Stream URL
        withYospaceSession()

        // It sets the debug Flags for the Yospace session
        withDebugFlags(int debugFlags)

        //Enables custom renderings such as 360 or VR
        withCustomRenderer(RendererBuilder builder, int interactiveMode, int displayMode, int projectionMode)

8) Be sure to notify AMP of at least these lifecycle events:

@Override
public void onResume() {
    if (amp != null) amp.onResume();
    super.onResume();
}

@Override
public void onPause() {
    if (amp != null) amp.onPause();
    super.onPause();
}

@Override
protected void onDestroy() {
    if (amp != null) amp.onDestroy();
    super.onDestroy();
}

The VideoPlayerContainer and VideoPlayerView objects you would use on a basic integration are still accessible if needed. There might be some more complex use cases that need the API exposed by these classes:

    amp.getVideoPlayerContainer();
    amp.getVideoPlayerView();

Ad providers

There are two options to initialize Ads using AmpPlayer:

Set the AmpPlayer with a single ad plugin only:

amp.setAdsPlugin(googleAds, iAdsComponentListener);

or set the AmpPlayer with a single ad plugin and multiple analytics plugins:

amp.setPlugins(googleAds, akamaiMediaAnalytics, streamsenseAnalytics, nielsenAnalytics);

The creation of those plugins varies, so check the AmpPlayerSample Android Studio project and every individual plugin sample.

The first parameter in the setPlugins() method above receives a com.akamai.amp.ads.IAdsPlugin:

  • AmpIMAManager: IMA.create(this);

  • AmpDAIManager: DAI.create(this);

  • AmpFreewheelManager: Freewheel.create(c, FW_NETWORK_ID, FW_ADS_URL, FW_SITE_SECTION_ID, FW_VIDEO_ASSET_ID, FW_PROFILE);

  • AmpYospaceManager: Yospace.create(activity, streamURL);

  • AmpFacebookAudienceNetworkManager: FacebookAds.create(PLACEMENT_ID, ADS_AT_SECONDS);

Analytics trackers

The other parameters for the setPlugins() method call extend from the com.akamai.amp.analytics.BaseTracker class. Those classes receive a com.akamai.amp.analytics.AnalyticsTrackerData in their constructor:

  • AmpAkamaiMediaAnalyticsTracker (MediaAnalyticsData)

  • AmpComscoreStreamsenseAnalyticsTracker (StreamsenseData)

  • AmpAdobeHeartbeatAnalyticsTracker (HeartbeatData)

  • AmpNielsenDcrAnalyticsTracker (NielsenData)

  • AmpGoogleAnalyticsTracker (GoogleAnalyticsData)

  • AmpFirebaseAnalyticsTracker (FirebaseTrackerData)

Notes:

  • The instantiation of plugins is the same if you use this approach or the VideoPlayerView and VideoPlayerContainer classes directly.

  • All of the AMP plugins are also notified of the lifecycle events by the AmpPlayer class.

  • If you have further questions or comments, reach out to us via amp-sdk-support@akamai.com

Last modified: 14/3/2023, AMP Support.