Firebase Analytics
The following document describes how to implement Analytics Firebase from the AMP Android SDK.
Introduction
Before you continue be aware that AMP Android SDK can be integrated with different approaches:
-
AMP Basic Integration: AMP Android SDK has a standard API to implement all features. AMP Basic Integration. It requires more code development and gives more freedom. For example: it allows UI control customization, rebuild the UI Controls completely, integration of Server Side Ad Insertion like DAI and Client Side Ad Insertion like IMA at the same time.
-
AMP Player Wrapper Integration: AMP Android SDK has a Wrapper module called AmpPlayer module. This module simplifies the implementation even further. It is intended for customers who want a quick integration, with almost no customizations and a default UI. The AMP Player module unifies and coordinates all the different plugins we provide: playback, UI (scrubbar, buttons and events), Close Captions, ads and analytics. With this new module we are saving the developer most integration effort, by providing a single drag and drop plugin that will provide production quality results in a matter of a few minutes.
Reach out to us at amp-sdk-support@akamai.com with any questions or concerns.
API notice
This tutorial describes how to integrate the Firebase feature using the default more detailed way to implement AMP, however we also provide an out of the box, all wrapped implementation, using the AmpPlayer module. Feel free to check both options and select the one better suited for your needs.
Prerequisite
The rest of this guide assumes you have successfully integrated AMP’s Core (you are able to play back a video): Basic Integration
It also assumes you have created a Project in the Firebase Google console, and successfully generated a google-config for your specific App. For further information, check out Google’s official Firebase website.
Getting started
For reference, check the AmpAnalyticsFirebaseSample
Android Studio sample project in the release package. To integrate the plugin into your app, you need to:
1) Add the following .jar to your project’s /libs folder:
-
amp-analytics-firebase.jar (provided by Akamai)
2) On the project’s build.gradle script, add the google services plugin dependency,
classpath 'com.google.gms:google-services:4.3.2'
On the executable module build.gradle script, add the dependendy for the firebase library,
implementation 'com.google.firebase:firebase-analytics:17.2.0'
and add the google services plugin at the top of the build.gradle script:
apply plugin: 'com.google.gms.google-services'
3) When you create a project on the Firebase Console, you need to add your Android App by using its package name, when you do it, a json file is autogenerated, you need to copy it into your project at the root of your executable module (often called app), this file is called google-services.json and it is the Id the Firebase implementation will look for to link the events fired in your App to your dashboard.
4) In the Activity where playback is handled, import the following Java packages:
import com.akamai.amp.analytics.firebase.AmpFirebaseAnalyticsTracker;
import com.akamai.amp.analytics.firebase.AmpFirebaseEvent;
import com.akamai.amp.analytics.firebase.FirebaseTrackerData;
5) Add an object of the AmpFirebaseAnalyticsTracker
type in your Activity’s members:
private AmpFirebaseAnalyticsTracker firebaseAnalytics;
6) Initialize that object, on the onResourceReady()
method from the VideoPlayerContainerCallback:
FirebaseTrackerData data = new FirebaseTrackerData();
firebaseAnalytics = new AmpFirebaseAnalyticsTracker(playerView, data);
The AmpFirebaseAnalyticsTracker
receives two parameters, the first one is the a reference of the VideoPlayerView
object from the core, and the second is a Data class called FirebaseTrackerData
.
The Firebase tracker doesn’t fire events unless the integrator adds them to the FirebaseTrackerData
, by calling the following method:
setTrackEvents(List of Events here);
There are three types of events:
PLAYBACK: It includes all playback related events suchs as start, stop, play, pause, resume, bitrate switch, buffering, etc.
ADS: It includes all Ads related events suchs as ad start, ad end, ad pause, ad resume, ad load, etc.
CAPTIONS: It includes two events, enable and disable captions.
These events are called multi tags, because they enable a collection of events all at once. However, you can cherrypick specific events from the group instead of selecting all, these are called single tag events, and using the same method you can use a combination of the two.
Here there are a couple of examples:
setTrackEvents(AmpFirebaseEvent.PLAYBACK, AmpFirebaseEvent.AD_END, AmpFirebaseEvent.ENABLE_CAPTIONS);
setTrackEvents(AmpFirebaseEvent.ADS);
setTrackEvents(AmpFirebaseEvent.ADS, AmpFirebaseEvent.RESUME, AmpFirebaseEvent.PAUSE, AmpFirebaseEvent.BITRATE_SWITCH);
This is the list of all single tag events available to choose:
- PLAY - STOP - START - RESUME - PAUSE - BUFFER_START - BUFFER_END - SEEK_START - SEEK_END - ERROR - ON_BACKGROUND - ON_FOREGROUND - BITRATE_SWITCH - END - AD_LOAD - ADBREAK_START - AD_START - AD_PAUSE - AD_RESUME - AD_END - ADBREAK_END - AD_ERROR - CAPTIONS_ENABLE - CAPTIONS_DISABLE
There is another feature available on this tracker, and it is called AmpFirebaseCustomParams
. Each log event allows you to send a Bundle with information, our tracker sends some information by default, but the integration can provide extra information for each of the single tag, or multi tag events. There is also an option to attached info to all events, including custom ones you might define.
To achieve that, you need to use the following method:
setCustomParams(yourAmpFirebaseCustomParams);
To define your custom parameters, you need to create a class that extends from AmpFirebaseCustomParams
, this class contains one method for each event which returns a Bundle object, you just need to create the class, override the method for the specific event you want to add more info, and then create an instance of the class and pass it to the tracker using the method above.
Here is an example of how that class would look:
private class CustomAmpFirebaseParams extends AmpFirebaseCustomParams{
//This method attaches new info to all events
@Override
public Bundle getGlobalCustomParams() {
return your_Bundle_with_new_Info;
}
//This method attaches new info to all playback events, there's another method for Ads and Captions events as well
@Override
public Bundle getPlaybackCustomParams() {
return your_Bundle-with_new_Info;
}
//This method attaches new info for the pause event in particular there's one method for each single tag event available
@Override
public Bundle getPauseCustomParams() {
return your_Bundle_with_new_Info;
}
}
7) If your app integrates ads, it should use the corresponding AMP Plugin for integration with Firebase. This example assumes Google IMA Ads. Once the com.akamai.ima.AdsComponent is initialized, it has to send the different events to AMP’s FirebaseTracker:
adsComponent.addEventsListener(firebaseAnalytics);
8) You can also send custom events and user properties, different from the default onces provided by the tracker. For user properties simply call the following method:
tracker.setUserProperty(KEY, value);
And for custom events, your can create a custom log with its specific bundle of data, or create a custom log which belongs to one of the multitags available, for example an extra playback or ad event. It will allow you to send your custom event, but also attached any extra data you might defined on the AmpFirebaseCustomParams
implementation.
//This method will fire an independent custom log event
tracker.logCustomEvent(key, dataBundle);
//This method will fire a custom log event, but with a parent which it can be any of the multi tags events, PLABYACK, ADS or CAPTIONS.
tracker.logCustomEvent(parent, key, dataBundle);
If you have further questions or comments, reach out to us via amp-sdk-support@akamai.com