Analytics SDK Architecture
This article provides a high level overview of the Amplitude Analytics SDKs. Our latest SDKs share a common architecture that works similarly across all platforms making it easy to understand how Analytics works regardless of the exact environment and runtime.
There are still some SDKs that haven't updated to the latest architecture, while also not in maintenance (1), for example Flutter, Java, and iOS.
- Maintenance SDKs are time-tested, stable versions of older SDKs. Once a new SDK is available for a given platform, the older SDK is moved to maintenance status and under the Maintenance SDKs section in the site navigation. Maintenance SDKs only receives bug fixes until deprecation. It's strongly recommended to new SDKs to take advantage of their benefits. To migrate from a maintenance SDK, refer to the migration guide under each maintenance SDK documentation.
Refer to the SDK status table to check whether a SDK follows the architecture.
Benefits of the latest architecture¶
-
Uses modern languages for each platform and with modern tools/frameworks
- It's easier for develpers to onboard Amplitude and also gain more confidence on data quality
- Latest Browser, Node.js, React Native SDK use TypeScript. Latest Android uses Kotlin. Latest iOS uses Swift
- Improved the code readability can speed up your the developement cycle
- Browser SDK implements tree-shaking technique to reduce the bundle size
-
Designed with a solid and extensible architecture
- Next generation SDKs allow more customization based on your needs. You can implement a custom logger and a custom storage, enrich your data, and send your data to other destination by using Plugins
-
Cleaner and aligned interfaces
- Aligned interfaces makes it easy to use the Amplitude SDKs on multiple platforms without memorizing different function names. For example, to track an event with different properties before the latest SDK, you needed to use different functions such as
logEvent()
,logEventWithTimestamp()
,logEventWithGroup()
, etc. With the latest SDKs, you can use now usetrack()
to set all available event properties.
- Aligned interfaces makes it easy to use the Amplitude SDKs on multiple platforms without memorizing different function names. For example, to track an event with different properties before the latest SDK, you needed to use different functions such as
-
More reliable and robust
- Latest SDKs don't require any external dependencies, which enhances performance, mitigates potential issues caused by dependencies, and makes them more lightweight
- Latest SDKs use file storage instead of database to improve performance
- Latest Android SDK removes OkHttp which addresses dependency compatibility issues
Latest Architecture¶
The latest SDKs share the same architecture and interfaces across platform. This page covers the high-level functionality across all latest SDKs. Refer to the individual SDK documentation for more detailed examples.
Client¶
Amplitude Client stores configurations and is the entry point for developers to interact with Amplitude. All major functionally is exposed on the Client including init
, track
, and flush
.
Before instrumenting events, you must initialize a SDK client instance using the API key for your Amplitude project.
Some SDKs exposes a default Client instance that can be used across the entire application.
// Latest Browser SDK example: initialize a Client
import * as amplitude from '@amplitude/analytics-browser';
amplitude.init('API_KEY');
But you can also create one Amplitude Client on your own . Refer to each SDK document for more details.
Configuration¶
All the latest SDKs allow for configuration of Client behavior. Below is a short list of common configuration settings and how to use them. Individual platforms may include additional configuration settings. Refer to the platform specific SDK documentation for a full list.
Configuration Options
Name |
Description | Default Value |
---|---|---|
apiKey |
Required. string . The apiKey of your project. |
null |
flushIntervalMillis |
number . The amount of time waiting to upload the event to the server in millionseconds. |
1 second. |
flushQueueSize |
number . The maximum number of events that can be stored locally before forcing an upload. |
30 events. |
flushMaxRetries |
number . The max retry limits. |
5 times. |
loggerProvider |
Logger . Implements a custom loggerProvider class from the Logger, and pass it in the configuration during the initialization to help with collecting any error messages from the SDK in a production environment. |
Amplitude Logger |
minIdLength |
number |
Overrides the minimum length of user_id & device_id fields. |
optOut |
boolean . If optOut is true , the event isn't sent to Amplitude's servers. |
false |
serverUrl |
string . The server url events upload to. |
https://api2.amplitude.com/2/httpapi |
serverZone |
EU or US . Set Amplitude Server Zone, switch to zone related configuration. To send data to Amplitude's EU servers should configure to EU |
US |
storageProvider |
Storage<Event[]> . Implements a custom storageProvider class from Storage. |
MemoryStorage |
useBatch |
boolean . When true , uses the Batch API instead of the HTTP V2 API. |
false |
You can pass a Configuration on Client initialization.
// Latest Browser SDK example: initialize a Client with a Configuration
import * as amplitude from '@amplitude/analytics-browser';
amplitude.init('API_KEY', 'OPTIONAL_USER_ID', {
flushQueueSize: 30, // flush queued events when there are 30 or more
flushIntervalMillis: 10000, // flush queued events every 1 seconds
useBatch: true //use batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
});
Storage provider¶
A storage provider holds events in a designated storage buffer. The default storage provider only queues events in memory. To prevent data loss, you can customize your own storage provider to persist events, for example to a disk, in case of unexpected shutdown. This way, you can ensure that you can recover un-sent events even in the event of a system failure.
You can configure the storage provider in the Client Configuration. Storage providers in different SDKs follows slightly different interfaces. Refer to the "Configuration Options" section of a specific latest SDK documentation for more details.
// Latest Browser SDK example: Customize the storage
class MyStorage<T> {
isEnabled(): Promise<boolean> {
// Whether the storage is enabled
}
get(key: string): Promise<T | undefined> {
// get the value associated with the given key in the storage
}
getRaw(key: string): Promise<string | undefined> {
// get the string associated with the given key in the storage
}
set(key: string, value: T): Promise<void> {
// set an item in the storage by key
}
remove(key: string): Promise<void> {
// remove an item in the storage by key
}
reset(): Promise<void> {
// clear the storage
}
}
amplitude.init('API_KEY', 'OPTIONAL_USER_ID', {
storageProvider: new MyStorage(),
});
Logger provider¶
A logger provider configures the logger instance used by the Amplitude Client. It helps to collect debugging and error messages from the SDK in both development and production environments. Logger providers in different SDKs follows slightly different interfaces. Refer to the "Configuration Options" section of a specific latest SDK documentation for more details.
// Latest Browser SDK example: Customize the logger
import * as amplitude from '@amplitude/analytics-browser';
// Log levels defined:
// None = 0,
// Error = 1,
// Warn = 2,
// Verbose = 3,
// Debug = 4,
class MyLogger{
disable(): void {
console.log('Logger has been disabled');
}
enable(logLevel: amplitude.Types.LogLevel): void {
console.log('Logger has been enabled with level:', logLevel);
}
log(...args: any[]): void {
// Implementation for the log method
console.log(...args);
}
warn(...args: any[]): void {
// Implementation for the warn method
console.log(...args);
}
error(...args: any[]): void {
// Implementation for the error method
console.log(...args);
}
debug(...args: any[]): void {
// Implementation for the debug method
console.log(...args);
}
}
amplitude.init('API_KEY', 'OPTIONAL_USER_ID', {
loggerProvider: new MyLogger(),
});
Event¶
Events represent how users interact with your application.
BaseEvent
represents a basic event with optional properties. You can also track other event properties in the field of event_properties
.
// Latest Browser SDK example: track an event
import * as amplitude from '@amplitude/analytics-browser';
import {BaseEvent} from '@amplitude/analytics-types';
const buttonClickedEvent: BaseEvent = {
event_type: 'Button Clicked',
event_properties: {
buttonColor: 'primary',
}
}
amplitude.track(buttonClickedEvent);
Some SDKs also allow you to track an event without creating one but just pass the event type as a string.
// Latest Browser SDK example: track an event without creating one
import * as amplitude from '@amplitude/analytics-browser';
// Track a basic event
amplitude.track('Button Clicked');
// Track events with optional properties
const eventProperties = {
buttonColor: 'primary',
};
amplitude.track('Button Clicked', eventProperties);
Plugins¶
Plugins allow you to extend Amplitude SDK's behavior. You can create a custom Plugin to modify or filter events, or send events to a custom destination. Please check here for more details.
Common methods¶
Latest SDKs share the same architecture as well as the same interfaces. Aligned interfaces benefit using Amplitude SDKs on multiple platforms without memorizing different function names.
This a list of shared interfaces of latest SDKs.
Note
Different SDKs follow different naming conventions. Here use camel case for methods and parameters and use pascal case for classes.
init(apiKey)
track(BaseEvent)
identify(IdentifyEvent)
setGroup(groupType, groupName)
groupIdentify(groupType, groupName, IdentifyEvent)
revenue(RevenueEvent)
flush()
add(Plugin)
remove(Plugin)
shutdown()
Comparison with maintenance SDK¶
If you are migrating from maintenance SDKs, you may notice that latest SDKs differ from maintenance SDKs not only in terms of interfaces but also in their Middleware vs Plugin architecture . You can think of Middleware as being equal to Enrichment Plugin and Destination Plugin. If you are migrating from maintenance SDKs, you may notice that latest SDKs differ in terms of interfaces.
logEvent()
has been renamedtrack()
.- Middleware has been replaced by Plugins . When migrating from Middleware, it be easily be converted to an Enrichment or Destination Plugin by overriding the
execute()
method.
SDK status table¶
Platform | Latest architecture | Not on latest architecture |
---|---|---|
Browser | @amplitude/analytics-browser Amplitude-TypeScript Document |
Maintenance SDK@amplitude/amplitude-js Amplitude-JavaScript Document |
Android | com.amplitude:analytics-android Amplitude-Kotlin Document |
Maintenance SDKcom.amplitude:android-sdk Amplitude-Android Document |
Node.js | @amplitude/analytics-node Amplitude-Typescript Document |
Maintenance SDK@amplitude/node Amplitude-Node Document |
React Native | @amplitude/analytics-react-native Amplitude-TypeScript Document |
Maintenance SDK@amplitude/react-native Amplitude-ReactNative Document |
iOS | AmplitudeSwift Amplitude-Swift Document |
Amplitude Amplitude-iOS Document |
Python | amplitude-analytics Amplitude-Python Document |
|
Go | github.com/amplitude/analytics-go analytics-go Document |
|
Unity | amplitude-unity.unitypackage unity-plugin Document |
|
Unreal | AmplitudeUnreal Amplitude-Unreal Document |
|
Flutter | amplitude_flutter Amplitude-Flutter Document |
|
Java | com.amplitude.:java-sdk Amplitude-Java Document |