media acceleration sdk - akamai · media acceleration sdk - integration guide (for android and...

March 20, 2017

Media Acceleration SDKIntegration Guide

(Version 1.2 - for Android and iOS/tvOS)

Title Page

Akamai Technologies, Inc

Akamai Technical Support: 1-877-425-2832 or, for routine requests, email [email protected] Luna Control Center, for customers and resellers: http://control.akamai.com

US Headquarters8 Cambridge Center

Cambridge, MA 02142

Tel: 617.444.3000Fax: 617.444.3001

US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices around the world, see: http://www.akamai.com/html/about/locations.html

Akamai® Media Acceleration SDK (ver. 1.2) - Integration Guide(for Android and iOS/tvOS)

Copyright © 2017 Akamai Technologies, Inc. All Rights Reserved.

Reproduction in whole or in part in any form or medium without express written permission is prohibited. The Akamai name, the Akamai wave logo, and the names of Akamai services referenced herein are trademarks of Aka-mai Technologies, Inc.

While every precaution has been taken in the preparation of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the use of the information herein. The informa-tion in these documents is believed to be accurate as of the date of this publication but is subject to change without notice. The information in this document is subject to the confidentiality provisions of the Terms & Conditions governing your use of Akamai services.

All product and service names mentioned herein are the trademarks of their respective owners.

http://www.akamai.com/html/about/locations.html

http://www.akamai.com/html/about/locations.html

http://control.akamai.com

ContentsCHAPTER 1. MASDK OVERVIEW • 5

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Integration Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Supported Target Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6tvOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

MASDK Package Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Files and Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

CHAPTER 2. THE MASDK FOR ANDROID • 9Building the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Build Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Using the MASDK in Your Own Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Easy Three Step Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Integrating the SDK with Google Cast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Collecting Logs to Report an Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Reducing the Footprint of the MASDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

CHAPTER 3. THE MASDK FOR IOS/TVOS • 15Building the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Build Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Easy Four Step Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16MASDK and the Xcode iOS/tvOS Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Collecting Logs to Report an Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21The Crash Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

APPENDIX A. COMMON/KNOWN ISSUES • 23Common Issues with Certificate Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Known Problems and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Need Help? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Media Acceleration SDK - Integration Guide (for Android and iOS/tvOS). Proprietary and Confidential iii

Contents

iv Media Acceleration SDK - Integration Guide (for Android and iOS/tvOS). Proprietary and Confidential

Chapter 1. MASDK Overview

In This Chapter

Overview

The Media Acceleration Software Development Kit (“MASDK”) lets Akamai cus-tomers enhance their applications using innovative technologies on phones, tablets, computers and other devices. This effectively extends the “Akamai Intelligent Plat-form” into a user’s device and adds the potential to dramatically improve the quality of the online user experience.

The Akamai Media Acceleration program will evolve over time to include multiple technologies, on multiple platforms as part of its modular architecture. In this phase, we are targeting devices running Android, iOS, and tvOS. We are performing high-quality video streaming over Apple HTTP Live Streaming (HLS) or Dynamic Adap-tive Streaming over HTTP (DASH), as well as downloads.

About This Document

This document will guide you through the steps required to smoothly integrate this Akamai software into your application. Using the SDK requires both the application integration and a server-side configuration. The former is discussed in this guide, while the latter requires assistance from your Akamai Representative.

Integration Plan

1. Kick-off Meetings - These are intended to bring Akamai and customers together to synchronize on plan and timing.

2. Integration of the MASDK into your Application

3. Testing - This includes Functional/QA testing and user acceptance testing, which may include partial deployment/release to the Production environment (in order to test on a subset of the user population).

4. Release to the Production Environment - This includes submission of an updated app to the App store.

5. Updates Made to the Configuration - This is followed by a Feedback Meeting, and new releases to the Production Environment, as necessary.

Overview • 5

Integration Plan • 5

Supported Target Platforms • 6

MASDK Package Contents • 7

Media Acceleration SDK - Integration Guide (for Android and iOS/tvOS). Proprietary and Confidential 5

MASDK Overview

Supported Target Platforms

NOTE: The tables that follow attempt to list the details for the most recent supported platforms. However, for an up-to-date list of current platforms, please visit the “Media Acceleration Akamai Community” space at: https://community.akamai.com/community/media-delivery/mae and search for “Mobile Platforms SDK”.

Android

iOS

tvOS

Version 4.0.0 (and higher)

API Level 14

ABI armeabi, x86

Latest Tested Environment android_sdk-r23.0.3

Version 7.0 (and higher)

ABI armv7, arm64

Latest Tested Environment Xcode version 8.0 beta 6

Version 9.0 (and higher)

ABI arm64

Latest Tested Environment Xcode version 8.0 beta 6

6 Media Acceleration SDK - Integration Guide (for Android and iOS/tvOS). Proprietary and Confidential

https://community.akamai.com/community/media-delivery/mae

MASDK Package Contents

MASDK Package Contents

The MASDK comes as a compressed zip archive comprised of platform-related con-tents.

Files and Directory Structure

Common

README.md Brief description of the SDK.

LICENSES Licenses of third-party software components used in the SDK.

version.txt Contains identification of MA SDK build.

Android

sample/app/ Pre-compiled sample application using the SDK.

sample/src/ Source code of the sample application using the SDK.

libs/MediaAcceleration.aar The Android Library file that implements the Media Acceleration API and the native libraries built for the armeabi and x86 platforms.

docs/javadoc This API is documented as a javadoc. After decompres-sion, the entry point can be found at “docs/javadoc/index.html.

iOS/tvOS

sample/MediaAccelerationSamplePlayer

Source code of an Objective-C sample application using the SDK, for iOS version 8.0 and higher, and tvOS version 9.0 and higher.

sample/SwiftMediaAccelerationSamplePlayer

Source code of a Swift 3 sample applica-tion using the SDK, for iOS version 8.0 and higher, and tvOS version 9.0 and higher.

framework_ios/MediaAcceleration.framework

The SDK packaged as an iOS framework, containing the native library built for the armv7 and arm64 platforms.

framework_tvos/MediaAcceleration.framework

The SDK packaged as a tvOS framework, containing the native library built for the arm64 platform.

docs/headerdoc This API is documented as a headerdoc, entry point is the `docs/headerdoc/Media-Acceleration.html` file.


MASDK Overview


Chapter 2. The MASDK for Android

In This Chapter

Building the Sample Application

Prerequisites JDK 1.8

Sample Application was Tested Using Android Studio v2.1.1 with Android SDK (API 23.0.3) - At the time of this publication, this tool and additional details on its use could be found here:

http://tools.android.com/download/studio/builds/2-1-1

Chapter 1: MASDK Overview Reviewed - Beginning on page 5 (specifically the sections pertaining to Android)

Build Process1. Download the Akamai Media Acceleration SDK for Android (“mediaaccel-

eration-sdk-android.zip”). This file can be found here:

https://control.akamai.com/dl/customers/MAE/mediaacceleration-sdk-android.zip

2. Decompress the file into your working directory. Going forward, this directory will be referred to as “$dir”.

3. Launch Android Studio. From the initial dialog, select the “Open existing Android Studio project” option.

4. Navigate to the following directory and access the following project:

5. Click OK.

6. To run the app, select Run> Run “app” and follow the instructions displayed in the subsequent dialog windows.

The Sample Player Main Class

The main class of the sample player is located as follows:

Building the Sample Application • 9

Collecting Logs to Report an Issue • 13

Reducing the Footprint of the MASDK • 14

$dir/sample/src/MediaAccelerationSamplePlayer

$dir/sample/src/MediaAccelerationSamplePlayer/app/src/main/java/com/akamai/mediaacceleration/sampleplayer/MainActivity.java


http://tools.android.com/download/studio/builds/2-1-1

https://control.akamai.com/dl/customers/MAE/mediaacceleration-sdk-android.zip

Chapter 2: The MASDK for Android

Using the MASDK in Your Own Project

If using an Android Studio project, and it is located at “$dir”, perform the following:

1. Copy the file “libs/MediaAcceleration.aar” to “$dir/app/libs/”.

2. Add the following lines to your module’s “gradle” build file (this is assumed to be at “$dir/app/build.gradle”):

Easy Three Step Integration1. Call “MediaAcceleration.start()” on application startup or before the first use

of the Media Acceleration SDK in your app. We recommend calling this method in the “onStart()” method of your Activity.

2. Before performing a download in your application code, pass the URL to be downloaded as a parameter to the “MediaAcceleration.getLocalhostURI()” function and use the returned modified URL for the HTTP download in a usual way. Repeat this step for as many downloads within your application as necessary.

3. When no further downloads are expected and/or your application is going to shut down, call “MediaAcceleration.stop()”. We recommend calling this method in the “onStop()” method of your Activity.

Additional Non-mandatory Code Changes

If during your application (while the MASDK is running), you wish to change the minimum level of log messages that the MASDK will log to the Android system log, call the following:

By default, the MASDK starts with the “ERROR” log level.

To add a domain where cookies can be shared between domains, call the following:

By default the MASDK uses the Android system's default “X509TrustManager” to verify X.509 certificate chains for a given hostname. However, if you wish to use a different X509TrustManager, you can use your own by calling:

You can also call your own custom chain verifier using the following:

repositories {flatDir {

dirs 'libs'}

}dependencies {

compile (name: 'MediaAcceleration', ext:'aar');}

MediaAcceleration.setLogLevel()

MediaAcceleration.allowCookieSharing()

MediaAcceleration.setCustomCertificateVerifier(X509TrustManager)

MediaAcceleration.setCustomCertificateVerifier(CertificateChainVerifier)



Integrating the SDK with Google Cast

To show how to use the Android SDK with Chromecast, we will modify Google's CastVideos-android v2.8.4 to explain the integration.

Prerequisites

Android Studio 2.1.1 (see page 9 for download link)

Android SDK (version 23)

Build Tools (version 23.0.3)

Setting Up the CastVideos-android Project

1. Download CastVideos-android v2.8.4 and decompress it into your working directory (this directory will be referred to as “$dir”). At the time of this publica-tion, this component (and additional details on its use) could be found here:

https://github.com/googlecast/CastVideos-android

2. Rename the “CastVideos-android-master” folder to “CastVideos”.

3. Sync the project with “gradle” files.

Add the MASDK to the CastVideos Project

1. Copy the “libs/MediaAcceleration.aar” file from the MASDK to “$dir/CastVideos/libs/”.

2. Update the “build.gradle (Module:CastVideos)” file by adding the following lines to the “dependencies” list:

3. In the “build.gradle (Module:CastVideos)” file, you need to change the “minSdkVersion” value to “14” (or higher), as shown in the example below:

4. Refresh the project and sync it with the “gradle” files.

repositories {flatDir {

dirs 'libs'}

}dependencies {

compile (name: 'MediaAcceleration', ext:'aar');}

android {...defaultConfig {

minSdkVersion 14...}

}


https://github.com/googlecast/CastVideos-android


Modifying the CastVideos App to Use the MASDK when Playing Locally

1. Navigate to the following directory:

2. In the activity, start the MASDK by adding the following lines to the “onCreate()” method, as close to the beginning of the method as possible (for example, before the call to “loadViews()”). Afterwards import the class.

NOTE: Although we usually recommend starting the MA-SDK in the “onStart()” method, in this case we do it in “onCreate()” to minimize the changes to the CastVideos example appli-cation.

3. In the activity, stop the MASDK by adding the following lines to the “onDe-stroy()” method, as close to the beginning of the method as possible:

4. When setting the video URI by calling “mVideoView.setVideoURI()”, obtain the URI via a “MediaAcceleration.getLocalhostURI()” call. In CastVideos-android v2.8.4, setting the video URI happens in two places: “onCreate()” and “togglePlayback()”.

5. Replace content “a.” with content “b.”:

a.

b.

$dir/CastVideos/src/com/google/sample/cast/refplayer/mediaplayer/LocalPlayerActivity.java.

// start the Media Acceleration SDKboolean isStarted = MediaAcceleration.start(getApplicationContext(),

MediaAcceleration.LOG_ERROR);if (!isStarted) {

Log.e(TAG, "Could not start the MediaAcceleration SDK. This should normally not happen.");

// The Media Acceleration SDK did not start properly.// We decide to close the activity. finish();return;

}

MediaAcceleration.stop();

mVideoView.setVideoURI(Uri.parse(mSelectedMedia.getContentId()));

String playbackUri = mSelectedMedia.getContentId(); try {

playbackUri = MediaAcceleration.getLocalhostURI( mSelectedMedia.getContentId());

} catch (IOException e) {Log.e(TAG, "Unable to obtain the localhost URI via Media

Acceleration: " +e.getMessage());}mVideoView.setVideoURI(Uri.parse(playbackUri));


Collecting Logs to Report an Issue

6. Update “VideoBrowserFragment.CATALOG_URL” to point to a JSON file that contains your links.

7. In class “VideoProvider”, comment out the lines that look for the MP4 category in the JSON:

8. To run the App, press “Shift + F10” in Android Studio and follow the instruc-tions displayed in the subsequent dialog windows.


The Android SDK offers a command line tool called “logcat” that can be used to capture Android logs. At the time of this publication, additional details on this tool could be found here:

https://developer.android.com/studio/command-line/logcat.html

Two types of information are important when reporting an issue:

The MASDK Log Messages - These are logged using the tag “masdk”, and

Android’s Crash Report - If the App crashes, Android will log information about the crash with the tag “DEBUG”.

The following two commands will first clear the log and then capture all “masdk” and “DEBUG” messages, and save them to the file, “logcat.txt”:

Ideally, the MASDK should be started with a log level of ‘debug’ when collecting logs. When the MASDK crashes, an Android “tombstone file” may reveal relevant information. If tombstone files can be collected on the device, provide these as well.

NOTE: Enabling logging may reveal user behavior information to the Android system log, includ-ing which URLs are visited.

TIP: The “Android Studio User Guide” offers a section on “Filtering Log Output”, that may be useful. It can be found at https://developer.android.com/studio/command-line/logcat.html#filteringOutput.

urlPrefixMap.put(TAG_MP4, category.getString(TAG_MP4));

adb logcat -c; adb logcat -v threadtime DEBUG:I masdk:V *:S > logcat.txt


https://developer.android.com/studio/command-line/logcat.html#filteringOutput

https://developer.android.com/studio/command-line/logcat.html#filteringOutput

https://developer.android.com/studio/command-line/logcat.html


Reducing the Footprint of the MASDK

Developers concerned with the footprint of their application can optimize for smaller download/install sizes by building separate Android Application Packages (APKs) for each supported architecture. Google offers a detailed overview of the topic, that includes various benefits and drawbacks. At the time of this publication, it could be found here:

https://developer.android.com/google/play/publishing/multiple-apks.html

The SDK supports multiple Android architectures, and it is possible to manually cre-ate an architecture-specific MASDK that is smaller. Removing an architecture will reduce the size of the final APK by roughly 2.5 megabytes.

The MASDK is distributed as an Android Library (AAR). This file is actually a regu-lar Zip file and its contents can be changed using regular Zip file manipulation tools.

To Remove Support for Android x86 - Delete the file “jni/x86/libma.so”.

To Remove Support for Android armeabi - Delete the file “jni/armeabi/libma.so”.

Relevant files in the “MediaAcceleration.aar” Android Library file:

IMPORTANT: Outside of the above Zip file content management options, it is important that you leave all other files untouched.

The modified SDK is used in exactly the same way with the only difference being that it no longer supports a removed architecture. Attempting to use the SDK on an unsupported platform will result in an error when the application is launched.

Length Date Time Name--------- --------- ----- ---------[...]

0 23-11-2016 11:33 jni/0 23-11-2016 11:33 jni/x86/6395412 23-11-2016 11:33 jni/x86/libma.so0 23-11-2016 11:33 jni/armeabi/5138224 23-11-2016 11:33 jni/armeabi/libma.so

[...]


https://developer.android.com/google/play/publishing/multiple-apks.html

Chapter 3. The MASDK for iOS/tvOS

In This Chapter


Prerequisites Xcode version 7.2 (or higher)

Sample Application was tested Using Xcode version 8 beta 6 - At the time of this publication, this tool and additional details on its use could be found here:

https://developer.apple.com/xcode/

Chapter 1: MASDK Overview Reviewed - Beginning on page 5 (specifically the sections pertaining to iOS/tvOS)

Build Process1. Download the Akamai Media Acceleration SDK for iOS/tvOS (“mediaac-

celeration-sdk-ios.zip”). This can be found here:

https://control.akamai.com/dl/customers/MAE/mediaacceleration-sdk-ios.zip

2. Decompress the file into your working directory. Going forward, this directory will be referred to as “$dir”.

3. Launch Xcode and select the “Open another project...” option (or select File > Open...).

4. Navigate to the following directory, select the following project and click Open:

5. In the project target, select a development team for code signing.

Building the Sample Application • 15

Collecting Logs to Report an Issue • 21

$dir/sample/MediaAccelerationSamplePlayer/Media Acceleration Sample Player.xcodeproj

Figure 3-1. Use the “Team” menu to select a Development Team for code signing.


https://developer.apple.com/xcode/

https://control.akamai.com/dl/customers/MAE/mediaacceleration-sdk-ios.zip

Chapter 3: The MASDK for iOS/tvOS

TIP: Apple provides detailed documentation on creating provisioning profiles -- https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html#//apple_ref/doc/uid/TP40012582-CH30-SW43.

6. To run the app, select Product > Run and follow the instructions displayed in the subsequent dialog windows.

The Sample Player Main Class

The main class of the sample player is located as follows:

iOS/tvOS Targets

The sample app contains an iOS target and a tvOS target. Each target contains its own version of the “storyboard”, “assets” and “Info.plist”.

Additional Notes:

The Sample Apps DO NOT Contain the Media Acceleration Framework - However, they do link to the respective frameworks in the “framework_ios” and “framework_tvos” folders.

The Swift Sample App is Written in Swift 3 (and requires Xcode 8).

Easy Four Step Integration1. On application startup (or before the first usage of the Media Acceleration SDK

in your app), call the method:

We recommend calling the above-noted method in:

If not using AirPlay, the SDK can be started in the following to conserve resources:

2. Before performing a download in your application code, pass the URL to be downloaded as a parameter to the following method:

Use the returned, modified URL for the HTTP download in the usual way. Repeat this step for all of the downloads in your application, as necessary.

$dir/sample/MediaAccelerationSamplePlayer/Media Acceleration Sample Player/ViewController.m.

[MediaAcceleration startWithLogLevel: targetQueue: enableAirPlay: completionHandler:]

[AppDelegate application: didFinishLaunchingWithOptions:]

[AppDelegate applicationWillEnterForeground:]

[MediaAcceleration getLocalhostURI: localOptionsMap: targetQueue: com-pletionHandler:]


https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html#//apple_ref/doc/uid/TP40012582-CH30-SW43




IMPORTANT: Do not store the converted links. Instead, request them again before each use. The SDK does not guarantee that the converted links are permanent, especially in the case of appli-cation backgrounding.

3. To release resources when no further downloads are expected, call:

We recommend calling the above-noted method in:

If the application is not using AirPlay, and the MASDK was started in:

you need to stop the MASDK in:

4. Add two "AppTransportSecurity" (ATS) keys to the application's "Info.plist" file, to allow your application to play back the converted URIs provided by the MASDK:

Adding these keys accomplishes the following:

"NSAllowsArbitraryLoads" - Adding this key disables ATS on iOS 9.

"NSAllowsLocalNetworking" - Adding this key disables ATS protection for unqualified domains and to “.local” domains, but not for the rest of the App. It also ignores "NSAllowsArbitraryLoads" for iOS 10 and higher.

NOTE: Adding these two keys will not trigger an App Store Review. More details on App Transport Security and relevant keys are available on the Apple Developer site:

https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009

Additional Requirements

The MASDK is dependent on the “libz.tbd” and “libc++.tbd” libraries. The “Media Acceleration.framework”, the “libz.tbd” and the “libc++.tbd” libraries need to be added to your target as Linked Frameworks and Libraries.

[MediaAcceleration stopWithTargetQueue: completionHandler:]

[AppDelegate applicationWillTerminate:]

[AppDelegate applicationWillEnterForeground:]

[AppDelegate applicationDidEnterBackground:]

<key>NSAppTransportSecurity</key><dict>

<key>NSAllowsArbitraryLoads</key><true/><key>NSAllowsLocalNetworking</key><true/>

</dict>



Additional Non-mandatory Code Changes

If you wish to change the minimum level of log messages produced by the MASDK, call the following while it is running:

Messages will be logged to the Apple System Log facility. By default, the MASDK starts with the “ERROR” log level.

To add a domain where cookies can be shared between domains, call the following:

Any domains added using this call are removed once the MASDK is stopped.

By default, the MASDK uses the iOS or tvOS system default certificate verifier to verify certificate chains for a given hostname. However, you can use your own cus-tom chain verifier, by calling the following:

Allowing AirPlay on iOS

This section only applies to Apps using iOS. Since an Apple TV device cannot AirPlay to another Apple TV device, it does not make sense to enable AirPlay for a tvOS App.

Convert the URL to a Modified URL that can be Played via AirPlay - To accomplish this, specify “enableAirPlay:YES” when starting the MASDK, and convert the URL using the method:

The method will specify to the completion handler whether or not the converted link is accessible by devices on the LAN.

Enable Streaming via AirPlay while the App is in the Background - This optional process is detailed in an Apple Technical Q&A:

https://developer.apple.com/library/ios/qa/qa1668/_index.html

The basis to the solution involves the following:

• Declare that the app is playing Audible Content while in the background

• Set the Audio Session category.

[MediaAcceleration setLogLevel:]

[MediaAcceleration allowCookieSharingWithScheme: domain:]

[MediaAcceleration setCustomCertificateVerifier:]

[MediaAcceleration getAirPlayURI: localOptionsMap: targetQueue: completionHandler:]


https://developer.apple.com/library/ios/qa/qa1668/_index.html


Using the MASDK from Swift

The MASDK provides an “Objective-C” API. This API can also be accessed from Swift and Xcode, and the compiler will do the interfacing automatically. The follow-ing steps will enable mixed-language support in an Xcode project and provide full access from Swift to the MASDK API from Swift:

1. Import the Media Acceleration framework into your project.

2. Create a new file (File > New > File...).

3. Choose to create a new “Objective-C” file, and name it “sideeffect.m”.

NOTE: The filename does not matter, as the file is only used to tell Xcode that this project mixes “Swift” and “Objective-C” code.

4. Xcode will ask if you want to create a “bridging header”. Confirm by answering, “Create Bridging Header”. Xcode will generate a file named “Yourproject-Bridging-Header.h”. Open this file in the editor and add the following line:

5. Save the file.

6. Add the “Media Acceleration.framework”, and the “libz.tbd” library to the application’s Linked Frameworks and Libraries.

7. Delete the original “Objective-C” file from Step 1. (optional).

Additional Notes:

The SDK Comes with a Swift Sample Player - See this app for more details on how to use the MASDK from Swift.

The Swift Sample App is Written in Swift 3 (and requires Xcode 8).

MASDK and the Xcode iOS/tvOS Simulator

Currently, MASDK does not work with the Xcode iOS/tvOS Simulator. You will receive a “linker error” when attempting to build your app using it along with the MASDK, similar to the following:

This error occurs because the MASDK is a framework that contains a multi-architec-ture library (also referred to as a “fat library”). The fat library bundles a “lib” for each supported platform. In a fat library, all bundled libraries must either enable “bitcode”, or all must disable it.

#import <MediaAcceleration/MediaAcceleration.h>

Undefined symbols for architecture x86_64: "_OBJC_CLASS_$_MediaAcceleration", referenced from: objc-class-ref in ViewController.o objc-class-ref in AppDelegate.old: symbol(s) not found for architecture x86_64.



What is “Bitcode”?

Bitcode is an intermediate representation of the compiled code that Apple uses to optimize the installation of iOS, tvOS and watchOS applications. Although optional for iOS, Apple requires that all tvOS and watchOS apps enable bitcode.

Unfortunately, the “x86” and “x86_64” platforms used in the Xcode iOS/tvOS Sim-ulators do not support libraries using bitcode. Therefore, they cannot be enabled in the official MASDK, which supports the following platforms:

“armv7” (iOS, only)

“arm64” (iOS and tvOS)

Potential Workaround

We offer a separate MASDK release that supports these simulators. Contact your Account Representative to obtain this version of the SDK.

Before you obtain and implement the simulator-enabled version of the SDK, take the following into consideration:

This version only supports the “x64_64” platform

This version does not support enabling bitcode (each bundled library with a fat library must disable it)

This version should not be used in apps that are to be submitted to the AppStore.

Additional Information

For more details on Apple Frameworks:

https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html#//apple_ref/doc/uid/20002303-BBCEIJFI

For more details on Bitcode:

https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/AppThinning/AppThinning.html


https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html#//apple_ref/doc/uid/20002303-BBCEIJFI





The MASDK performs logging via “NSLog” to the Apple System Log (additional details can be found in the man page, “man 3 asl”). Apple also offers additional documentation on NSLog, including how to redirect this output to a file. At the time of this publication, this documentation was available here:

https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Functions/#//apple_ref/c/func/NSLogv

NOTE: Enabling logging may reveal information about the user behavior to the Apple System Log, including which URLs are visited.

The Crash Report

If the application crashes, it is important that you gather the “Crash Report” gener-ated by the OS (including stack traces), for use in troubleshooting the problem. You can extract application crash reports from a device using Xcode. Apple offers a guide on this process, Viewing Crash Logs on a Device. At the time of this publication, it could be found here:

https://developer.apple.com/library/mac/recipes/xcode_help-devices_organizer/ViewingCrashLogsonaniOSDevice/ViewingCrashLogsonaniOSDevice.html

Crash Report Requirements

Crash Reports must be “Symbolicated” Before being sent to Akamai - In most circumstances, Xcode will do this automatically when reading the log from the device.

Embedded Bitcode and Obfuscation - If the application was built with embedded bitcode and obfuscation is enabled, the crash log must be “de-obfus-cated” before being sent to Akamai. Bitcode is mandatory on tvOS, but optional on iOS.

Crash Reports Should Use Apple’s Standard Crash Format - If a third party crash reporter is used, it should have tools for converting its reports into Apple’s format.


https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Functions/#//apple_ref/c/func/NSLogv

https://developer.apple.com/library/mac/recipes/xcode_help-devices_organizer/ViewingCrashLogsonaniOSDevice/ViewingCrashLogsonaniOSDevice.html

Appendix A: Common/Known Issues

Common Issues with Certificate Validation

The MASDK only accepts X.509 certificates that live up to modern security stan-dards, as well as modern TLS Cipher Suites. If a certificate is outside of these for-mats, the custom certificate verifier will not be consulted.

If problems arise when accessing content via the MASDK using HTTPS or QUIC, logging with the “debug” log level should be enabled to identify the problem. Below are a few examples of this, including the corresponding log messages.

Example 1: SHA1-certificate:

Example 2: RC4 is Part of the Cipher Suite:

Known Problems and Limitations

Android The Native Library is 32-bit - The native library is built only for 32-bit plat-

forms (only armeabi and x86). The MASDK will run on Android arm64-v8a plat-forms, as long as all of the native libraries loaded by the Android application are 32-bit.

Need Help?

For additional information and assistance, visit the Media Acceleration Akamai Community space:


I/masdk: [Handshake] [Client-CTX:583][SSL:cca] Handshake has shut down with status Signature algorithm should use SHA256, SHA384 or SHA512, but this one doesn't: 1.2.840.113549.1.1.5, long name: sha1WithRSAEncryption

I/masdk: [Handshake] [Client-CTX:f69][SSL:7c7] Handshake has shut down with status Handshake has failed: error:14094410:SSL routines:ssl3_read_-bytes:sslv3 alert handshake failure



Chapter A: Common/Known Issues


media acceleration sdk - akamai · media acceleration sdk - integration guide (for android and...

Documents