Getting Started with the Mobile App Performance (MAP) SDK

March 20, 2017 · by Gokul Sengottuvelu and Aman Alam ·

The Mobile App Performance software development kit (MAP SDK) helps you create seamless mobile experiences when connection speeds are slow, or even unavailable. The MAP SDK manages this by intelligently pre-positioning content on the mobile device. The SDK also provides you with real user and device insights, including custom metrics, that can help you tune mobile experiences over time.

If you’re already using Akamai Ion, it shouldn’t take too much effort to get started with the SDK. The high-level steps are:

  1. Create a new policy app from Luna.
  2. Download the SDK and include it in your app.
  3. Register and start using it.

The first step is the same for both Android and iOS, thereafter, the instructions are specific to the OS.

Create a New Policy App from Luna

Before you can download the SDK, there are a few configuration steps in Luna, and then you generate the SDK key and download the SDK.

  1. In the Luna Portal (, under the Configure tab, click Mobile App Perf SDK. This will take you to the page where you can view the existing policies, and create new ones as well.
  2. Click Add a new App.
    • On the New App page, fill in details about the app (e.g., name and package id/bundle id).
    • Turn Network Quality Detection to On and fill in your domain. Leave the other settings as is for now.
    • Click Save Changes, which saves your settings and allows you to download the SDKs and generate the license key.
  3. To use the SDK in the app, you’ll need to initialize it with a license key in your app code. To get the license key, click Copy SDK License Key.
  4. Now click the Actions drop-down list and select the SDK for iOS or Android. You'll download a zip file that contains the SDK itself, integration guides, and sample codes.


The following steps are different for Android and iOS, so skip ahead in the instructions as required by the OS.

Integrate the SDK in Android

To integrate the SDK with your Android app, you'll need to add the SDK to your build.gradle file, declare required dependencies, and then add the Meta Data and Content Provider required by the SDK.

  1. Add the MAP SDK in your build.gradle file. The MAP SDK has a dependency on Google Play Services, and the Support Library, so don’t forget to include them in your project by adding them to your build.gradle file of your app (not project):

    dependencies {
        compile ''
        compile ''
        compile '<version>@aar'


  2. In the AndroidManifest.xml file of your app, declare the Content Provider that the SDK requires, along with the meta-data pointing to the configuration file:
        android:resource="@xml/android_sdk_init" />
  3. Now create the MAP SDK configuration file inside the res/xml/ folder, with the name android_sdk_init.xml, and put the following code:
    <?xml version="1.0" encoding="utf-8"?>
        <!--SDK license key created on portal-->
        <!--In case of MAP license, this is comma separated list of 
        segments to register with (optional)-->
        <com_akamai_sdk_segments><!--Default Segments--!></com_akamai_sdk_segments>
        <!--Regional info (optional)-->
        <!--SDK user id specified by the app (optional)-->

You're now ready to start writing code, using the MAP SDK in your Android apps.

Initialize and use the SDK

Initialize the SDK in a base or root activity, by calling the following method:

VocService vocService = VocService.createVocService(getApplicationContext());

If your app structure is such where there’s a base class extending Application class, and all the further activities extend from this base class, then initialize this SDK in the base class.

After this point, the SDK will pick the license key and the default segments (if any) from the configuration file, and register itself automatically.

After this point, you should be able to use the various SDK methods using the vocService object.

For detailed documentation, refer to the Integration guide provided with the SDK Zip file.

Integrate the SDK in iOS

To integrate the SDK with your iOS app, you'll need to add the SDK as a project and rename it.

  1. To integrate the SDK with your iOS app, unzip the MAP SDK Zip file into your project folder and rename it to voc_sdk.
  2. Copy the framework from ~/myproject/voc_sdk/iphoneos/VocSdk.framework into your project folder at ~/myproject/VocSdk.framework. This allows Xcode to recognize the framework before the first build. Each build afterward will copy the correct framework (either device or simulator) into place using the copy_vocsdk build phase script. 3. Add VocSdk.framework to your project file. 4. Link the SDK as an embedded library to your project. Embedded libraries can be found in the General tab when you click on the project name in the files navigator.

To ensure that the right framework is built for the right target (Device or Simulator), you have to add a build phase.

  1. In project settings, navigate to Build Phases and add a new build phase.
  2. Rearrange the build phase settings so that it is after the target dependencies. You could optionally rename it to copy_vocsdk for better understanding.
  3. Now expand the setting by clicking on the arrow.
  4. Leave the default shell setting of /bin/sh.
  5. Add the following in script area.

    ./voc_sdk/ “${PROJECT_DIR}/voc_sdk”

Note that “${PROJECT_DIR}/voc_sdk signifies the location of the /iphoneos and /iphonesimulator folders from the distribution archive. This script ensures that the correct framework will be available in the project folder linked to the xcode project file.

The build phase should ideally look like this, once you have followed the steps:

Initialize the SDK

Initialize the SDK by using: VocServiceFactory createAkaWebAccelerationWithDelegate:delegateQueue:options:error:

Since the acceleration needs to available to the app as soon as it starts up, you must initialize and register in the application delegate method application:didFinishLaunchingWithOptions:

The code snippet below demonstrates the SDK initialization and makes the app delegate object to delegate the handling of all the callbacks from the SDK.

- ( BOOL ) application :( UIApplication *) application didFinishLaunchingWithOptions 
    :( NSDictionary *) launchOptions

NSError * error = nil ;
self . akaService = [ VocServiceFactory createAkaWebAcceleratorWithDelegate : self

delegateQueue :[ NSOperationQueue mainQueue ] options : nil
error :& error ];

if (! self . akaService ) {
// error handling - could not start service

return NO ; }

// app initialized                        
return YES ; 


Registering the SDK

In order to activate the VOCService , you need to register the SDK with an licence key and an array of segments. The key plays the significant role in mapping the app to the prepositioned content, usage statistics and other related SDK capablities.

The return type to method which is used for registration will be VocService. The VocService contains an instance called state which indicates whether the registration is succeeded for the particular device. It is prudent to check with the state propery every time before you commence the registration.

[appDelegate . akaService registerWithLicense : sdkLicense 
                           segments : segments  
            completion :^( NSError * __nullable error ) {
        if ( error ) { // handle failed registration }; 

Understanding Segments and Segment Subscriptions

It is important to understand Segments and how to subscribe the app to the segments. The content prepositioning is a vital feature of the SDK. The contents are ingested during the content ingest phase and the SDK prepositions the content making it available instantly to the user.


A segment is a unique string which represents a particular category of content. For example, an e-commerce app could have segments for “Winter clothing”, “Swimsuits” etc., Your mobile app can subscribe to one or more segments, which can be pre-positioned using the Ingest API.

Once You decide which app users need to fall under what categories, you can program the app to subscribe to the corresponding segments. So in our earlier example, an app could subscribe to two segments "Winter Clothing" & "Swimsuits" and have that content prepositioned.

Subscribing to Segments

Apps can subscribe to segments by specifying the segment strings during the registration phase. You can see in the example code above for iOS and Android, how the code segments are specifying the segments while registering.

Sending Data to Segments Using the Ingest API

Once the apps start registering to the correct segments as per the category they fall on, in a certain device, you can use Ingest API to send, or ingest content to those segments, to specify what images should be prepositioned for what segments.

For a detailed information on what is Ingest API and how to use it, please refer to the documentation provided in the Zip file you downloaded.

Additional Resources

The home page for the Mobile Application Performance SDK contains lots of useful information and links. Check back often, as we're regularly updating the content.

About the Authors

Aman and Gokul are developer evangelists with Akamai Developer Relations Team.

Aman Alam

I work on the Android side of things, with a good amount of experience in building Android apps with the native Android platform. SDKs are a great way to boost productivity in your development cycle and to make sure that you don't re-invent the wheel to do things that the SDKs out there can do very well. At Akamai, I help our customers and other developers understand how Akamai can help them build the best performing apps out there.

Gokul Sengottuvelu

I specialize in iOS development, and have been part of various world-class mobile SDK development teams. I believe that robust SDKs accelerate mobile app development and just make life a whole lot easier for developers. At Akamai, I'm involved in customer-centric initiatives in which the performance of mobile apps becomes really crucial. I also advocate for Akamai's mobile SDKs and represent the developer communities internally.