IMPLEMENTATION BEST PRACTICES
Last updated: 8.6.2014
This implementation best practices document will guide you through the process we believe will get you the most value out of Amplitude. Our philosophy is to take integration step by step and understand what you’re able to see in our dashboards before moving on to more advanced functionality. Implementing correctly the first time will save time and headaches in the long-run.
Table of Contents
Step 1: The API Key and Separating Production from Test Data…
pg 2
Step 2: Establish The Minimum Viable Product…
pg 4
Step 3: Assign User IDs and Properly Identify Users…
pg 6
Step 4: Track Events and Understand the Actions People Take…
pg 7
Step 5: Set Custom User Properties and Custom Event Properties…
pg 9
Step 6: Track Revenue…
pg 11
Step 1: The API Key and Separating Production from Test Data
We are often asked if the same API key should be used for the iOS and Android versions of the same app or to tie Web and Mobile data together.
The quick answer is that it highly depends on the kind of apps you have and the kind of analysis you want to do.
Conditions to Consider Using the Same API Key:
● You expect frequent user crossover between platforms (we recommend including an event property called “platform” with each event so that you can break them out analysis)
● You want to analyze user behavior across platforms (requires user_id system) as a key focus for your company
● You have had experience using the same API key in another analytics product ● You have read and understand the advantages for using different API keys (below) Advantages
● Totals: You can see totals across all platforms in one view
● Cross Platform Analysis: You can create funnels/retention charts that analyze user behavior across platforms
Conditions to Consider Using Different API Keys:
● Your app acts as a standalone on each platform and user crossover analysis is not important ● Your focus as a company is to understand how users are engaging within each platform Advantages
● Platform Differences: even if your app has the same primary functions on iOS and Android, there are slight differences when it comes how certain actions are tracked (ex. asking for permissions) that you will want to separate. Slight differences in the apps themselves (ex. showing different landing/tutorial screens) will be best managed if separated as well
● Different Update Cycles: instrumentation changes happen all the time and it’s rare that app updates are released on the same day, meaning data and possibly new events from a new version on a certain platform could be mixed in with data and olde events on the old version, polluting the dashboard and taking focus away from the important metrics
● Difficulty of Finding Errors: having events from multiple platforms on the same dashboard makes it more difficult to spot errors and bugs in instrumentation and make the fixes necessary
● Web and Mobile are VERY Different: the experiences on web and mobile differ vastly and the kinds of events you’ll want to track will be very different. Additionally, Amplitude’s dashboards are geared to mobile analytics so some functionality will be lost on web
● Faster Charts and Load Times: splitting data into different platforms will increase the the load time of segmented graphs as there are fewer users to query across
Every company has a unique case so if you’re unsure of how to implement, please contact
On top of that, we recommend creating two API keys for each production app you have. One API key should be used for testing/integration and the other should be used for production data. Keeping testing and production data separate will ensure that the numbers you are looking at accurately reflect how people are using your app. The entirety of this integration process should be done on the test app first before pushing to production.
Step 2: Establish The Minimum Viable Product (Active Users, New Users,
Session, Composition, Retention)
Getting the minimum viable product (MVP) in place will give you access to the most important app metrics active and new users, as a other information and the basic dashboarding features of Amplitude. To get the MVP in place, initialize the SDK:
Implementation For iOS
1. Download the source code and extract the zip file. Alternatively, you can pull directly from GitHub. If you use Cocoapods, add the following line to your Podfile:
pod 'AmplitudeiOS', '~> 2.1'
2. Copy the Amplitude-iOS folder into the source of your project in XCode. Check "Copy items into destination group's folder (if needed)".
3. In every file that uses analytics, import Amplitude.h at the top: #import "Amplitude.h"
4. In the application:didFinishLaunchingWithOptions: method of your YourAppNameAppDelegate.m file, initialize the SDK:
[Amplitude initializeApiKey:@"YOUR_API_KEY_HERE"];
For Android
1. Download the jar.
2. Copy the jar into the "libs" folder in your Android project in Eclipse. If you're using an older build of Android, you may need to add the jar file to your build path.
Alternatively, if you are using Maven in your project, the jar is available on Maven Central using the following configuration in your pom.xml:
<dependency>
<groupId>com.amplitude</groupId> <artifactId>androidsdk</artifactId> <version>1.4</version>
</dependency>
3. In every file that uses analytics, import com.amplitude.api at the top: import package com.amplitude.api;
4. In the onCreate() of your main activity, initialize the SDK:
Amplitude.initialize(this, "YOUR_API_KEY_HERE"); 5. Add a startSession() call to each onResume() in every activity in your app:
Amplitude.startSession();
6. Add an endSession() call to each onPause() in every activity in your app. This call also ensures data is uploaded before the app closes:
Dashboarding Functionality
Overview Tab: will now be fully functional with the MVP in place as we will be logging [Amplitude] Start Session and [Amplitude] End Session events automatically for you
- Daily Active Users (DAU): will show how many users have logged at least one event during each day. DAU is perhaps the most common and most important key performance indicator (KPI) used by app developers as it summarizes how many people engage with the app over time
- Daily New Users: will show how many users have logged their first event each day. When you first start using Amplitude, the new users number will be higher than normal because old users logging events on Amplitude for the first time will be considered new users. We recommend waiting about three weeks for the data to settle before analyzing new user data.
- Sessions: will show different graphs that summarize the session information we automatically grab with our SDK
- Composition of User Properties: will show you the breakdown of your users based on the user properties we automatically pull from the SDK (which have the [Amplitude] label). these properties include: app version, country, language, platform, OS, device, and carrier
- Segmentation on User Properties: will allow you to break down your active and new users into different segments for direct comparison
Retention Tab: understanding your retention is a powerful way to see if your app is sticky or if people are opening once and never returning. Our retention chart will visually show you if users are coming back to your app. With the MVP, you will be able to view the daily/weekly/monthly retention of new/active users base and be able to segment them based on user properties
Step 3: Assign User IDs and Properly Identify Users
*If you do not have a system of assigning user IDs (either client or server-side) you should skip this section. If you are using the same API key for multiple platforms and want to connect user data, you must complete this step.
Additionally, assigning user IDs properly can be tricky if you have a system that does it server-side. If you feel that you are running into issues assigning user IDs, please contact [email protected]*
Apps that have some kind of login system can benefit from being able to track users even if they switch devices.
Implementation For iOS
At anytime you can call:
[Amplitude setUserId:@"USER_ID_HERE"]; OR you can add the user ID as an argument to the initializeApiKey: [Amplitude initializeApiKey:@"YOUR_API_KEY_HERE" userId:@"USER_ID_HERE"];
For Android
At anytime you can call:
Amplitude.setUserId("USER_ID_HERE");
OR you can add the user ID as an argument to the initialize() call:
Amplitude.initialize(this, "YOUR_API_KEY_HERE", "USER_ID_HERE"); A user's data will be merged on the backend so that any events up to that point on the same device will be tracked under the same user. More information about how we count unique users can be found in the FAQ section of our documentation: https://amplitude.com/docs#faq
Step 4: Track Events and Understand the Actions People Take
The bulk of the events you track in Amplitude should reflect actions that users are taking in your app. Some developers may choose to track events to make sure that some of their internal processes are working correctly, and that’s perfectly fine too. Just remember that event-based analytics is all about understanding what users are actually doing in your app and that’s where you’ll get the most mileage out of Amplitude.
How Many Events Should I Track?
Apps on the with basic functionality might only require 20 events whereas a rich feature app might require 200. Our general recommendation is that you should not be tracking every single action in your app. You should be tracking any action that is important in completing a process within your app, like completing a tutorial or signup process, progressing through the main mechanic of your app, or making an in app purchase (IAP). If the process can be represented in a funnel, then you should be tracking the steps in that process. If you need help deciding what events to track please contact your CSM or
To start, we recommend basic tracking of your signup funnel. Tracking this allows you to quickly understand what the paint points in the first time user experience are. Once you feel confident in the basic tracking you’ve instrumented, you can expand to more detailed tracking of other areas of your app.
What Should I Name My Events? How Specific Should I be?
We strongly recommend naming your events as human readable strings. This is because if someone on your team wants to look at the data, they won’t understand it if the event names are written in
mysterious shorthand. It also makes it easier for you to come back and remember what an event tracks in case you ever forget.
How specific you want to be in your event name depends on how deep you want to go into your
analysis. Take for example an app that has three login options: login by email, login by Facebook, or login by Twitter. On one level, you might just be concerned to see if people are logging in at all and might log all those login options as a general “Login” event. On another level you might be concerned about which option users are choosing most often and how their experience differs; therefore, you’d want to track a separate event for each login: “Login Email” “Login Facebook” and “Login Twitter”. Right now, we recommend doing both so that you have that kind of data to dig into later on.
Implementation For iOS
[Amplitude logEvent:@"EVENT_IDENTIFIER_HERE"];
Amplitude.logEvent("EVENT_IDENTIFIER_HERE");
Events are saved locally. Uploads are batched to occur every 30 events and every 30 seconds, as well as on app close. After calling logEvent in your app, you will quickly see data appear on the Amplitude Website.
How do I Know if I’ve Instrumented Correctly?
In order to make sure that you’re instrumenting correctly, you can use the User Activity Tab on our dashboard. Using your test device you can open your app and see the device ID or userID appear on the realtime feed. Clicking on that ID will bring you to the event history stream. As you progress through the app you should see the list of events you’re tracking appear in the stream (you’ll need to refresh the page). If you’re not seeing the events you want to be tracking appear, there is most likely an error with how you’ve integrated.
Dashboarding Functionality
Funnels: will show you where your users are dropping off when attempting to a complete a process in your app. This is perhaps the most important dashboard feature in terms of understanding how your users engage with your app. Spend the time to create funnels that break your app down into individual processes and segment them on properties to find patterns and/or odd behavior. Looking at your funnels over time can help you gauge if you’re making choices that improve the user experience Events Tab: will show you a list of the events you are tracking. Clicking on an event will show you
statistics on that event such as the total number of times that event was triggered each day, the number of unique users who triggered the event, the average number of times a users triggered the event, and the percentage of DAUs who triggered the event
User Activity: will show you the event history of your users so you can better understand their flow through your app. This feature is also helpful to debug issues their users are having in the app Retention: allows you to specify specific events that users must satisfy for them to be considered retained
Cohorts: will allow you to group users based on behavior (ex. did the “Buy Item” event more than 5 times) and analyze them in any graph where you get segment users. These cohorts of users will appear in segmentation under the [Amplitude] Cohorts property
Step 5: Set Custom User Properties and Custom Event Properties
Custom user properties and custom event properties can give you a deeper analysis into how users are engaging with your app.
What is the Difference Between Custom User Properties and Custom Event Properties?
The most general explanation is that user properties are attached to users and reflect the current state of the user and event properties are attached to events and reflect the state at which the event was triggered.
User Properties
Reflect traits about the individual person using your app. Examples of of custom user properties are: age, gender, email, locale, referral source, plan type, number of photos uploaded, number of units of in-game currency, current level in a game. The most important thing to remember is that these user properties reflect the state of the user and apply across all their events.
Event Properties
Reflect more detailed information about an event at the time it was tracked. These properties highly depend on the type of app you have an the specific information you think is necessary for understanding a particular event. General keys we’ve seen are: cause, description, category, type, duration, level, % completed, name, count, source, status, from, number, lives, authenticated, error, rank, action, mode, etc.
Implementation For iOS
Custom Event Properties
Pass a NSDictionary object as the second argument to logEvent:withEventProperties:
NSMutableDictionary *eventProperties = [NSMutableDictionary dictionary]; [eventProperties setValue:@"VALUE_GOES_HERE" forKey:@"KEY_GOES_HERE"]; [Amplitude logEvent:@"Compute Hash" withEventProperties:eventProperties]; Custom User Properties
NSMutableDictionary *userProperties = [NSMutableDictionary dictionary]; [userProperties setValue:@"VALUE_GOES_HERE" forKey:@"KEY_GOES_HERE"]; [Amplitude setUserProperties:userProperties];
For Android
Custom Event Properties
Pass a JSONObject as the second argument to logEvent():
try {
eventProperties.put("KEY_GOES_HERE", "VALUE_GOES_HERE"); } catch (JSONException exception) {
}
Amplitude.logEvent("Sent Message", eventProperties); You will need to add two JSONObject imports to the code:
import org.json.JSONException; import org.json.JSONObject; Custom User Properties
JSONObject userProperties = new JSONObject(); try { userProperties.put("KEY_GOES_HERE", "VALUE_GOES_HERE"); } catch (JSONException exception) { } Amplitude.setUserProperties(userProperties); Dashboarding Functionality
Segmentation: with custom user properties, you’ll be able to segment based on those properties in any graph that allow segmentation. Your custom user properties will appear after the automatic [Amplitude] pulled properties in the dropdown menus.
Events Tab: with custom event properties, you’ll be able to analyze the different keys you have associated with each event and see the distribution of the values
Step 6: Track Revenue
*If you do not track IAPs you should skip this section.*
Our revenue tracking authenticates purchases before logging revenue events so you can be sure that the data you’re seeing is legitimate.
Implementation For iOS
To track revenue from a user, call
[Amplitude logRevenue:@"productIdentifier" quantity:1 price:[NSNumber numberWithDouble:3.99]]
after a successful purchase transaction. logRevenue: takes a string to identify the product (can be pulled fromSKPaymentTransaction.payment.productIdentifier). quantity: takes an integer with the quantity of product purchased. price: takes a NSNumber with the dollar amount of the sale as the only argument. This allows us to automatically display data relevant to revenue on the Amplitude website, including average revenue per daily active user (ARPDAU), 7, 30, and 90 day revenue, lifetime value (LTV) estimates, and revenue by advertising campaign cohort and daily/weekly/monthly cohorts.
To enable revenue verification, copy your iTunes Connect In App Purchase Shared Secret into the manage section of your app on Amplitude. You must put a key for every single app in Amplitude where you want revenue verification.
Then call
[Amplitude logRevenue:@"productIdentifier" quantity:1 price:[NSNumber numberWithDouble:3.99 receipt:receiptData]
after a successful purchase transaction. receipt: takes the receipt NSData from the app store. For details on how to obtain the receipt data, see Apple's guide on Receipt Validation.
For Android
To track revenue from a user, call logRevenue() each time a user generates revenue. For example: Amplitude.logRevenue("com.company.productid", 1, 3.99);
logRevenue() takes a takes a string to identify the product (the product ID from Google Play), an int with the quantity of product purchased, and a double with the dollar amount of the sale. This allows us to automatically display data relevant to revenue on the Amplitude website, including average revenue per daily active user (ARPDAU), 1, 7, 14, 30, 60, and 90 day revenue, lifetime value (LTV) estimates, and revenue by advertising campaign cohort and daily/weekly/monthly cohorts.
To enable revenue verification, copy your Google Play License Public Key into the manage section of your app on Amplitude. You must put a key for every single app in Amplitude where you want revenue verification.
Then after a successful purchase transaction, call logRevenue() with the purchase data and receipt signature: // for a purchase request onActivityResult String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA"); String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE"); Amplitude.logRevenue("com.company.productid", 1, 3.99, purchaseData, receiptSignature);
See the Google In App Billing Documentation for details on how to retrieve the purchase data and receipt signature.
Dashboarding Functionality
Revenue Tab: will now show you ARPU, ARPPU, Total Revenue, and # New Paying Users for each daily cohort. You can segment the revenue table based on user properties and or custom behavior cohorts
Step 7: Explore the Dashboard and Redshift
Congratulations! By following the implementation best practices you’re in a great position to start analyzing your data in a meaningful way.
Our documentation has a deeper analysis of how to use our dashboarding features:
https://amplitude.com/docs
For enterprise clients who have access to their raw data in Amazon Redshift, consult the directions your CSM sent you about accessing your database and use the Redshift Best Practices guide to help you get started.
