You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+22-26Lines changed: 22 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,17 +38,17 @@ Amplitude-Javascript
38
38
39
39
Version 3.0.0 is a major update that brings support for logging events to multiple Amplitude apps (multiple API keys). **Note: this change may break backwards compatibility on your setup.** See the subsection below on backwards compatibility.
40
40
41
-
### Changes ###
41
+
### API Changes ###
42
42
43
-
The `amplitude` object can now maintain one or more instances, where each instance has a separate apiKey, userId, deviceId, and settings. These separate instances allow the logging of events to multiple Amplitude apps.
43
+
The `amplitude` object now maintains one or more instances, where each instance has separate apiKey, userId, deviceId, and settings. Having separate instances allows for the logging of events to separate Amplitude apps.
44
44
45
-
The most important API change is how you use the `amplitude` object. Before v3.0.0, you would directly call `amplitude.logEvent('EVENT_NAME')`. Now you will need to call functions on an instance as follows: `amplitude.getInstance('INSTANCE_NAME').logEvent('EVENT_NAME')` This notation will be familiar to people who have used our iOS and Android SDKs.
45
+
The most important API change is how you interact with the `amplitude` object. Before v3.0.0, you would directly call `amplitude.logEvent('EVENT_NAME')`. Now you will need to call functions on an instance as follows: `amplitude.getInstance('INSTANCE_NAME').logEvent('EVENT_NAME')` This notation will be familiar to people who have used our iOS and Android SDKs.
46
46
47
47
### Continue Logging Events to a Single Amplitude App / API Key ###
48
48
49
-
If you want to continue logging events to a single Amplitude App (and a single API key), then you will want to call functions on the default instance, which you can fetch by calling `amplitude.getInstance()` with no instance name. The code examples in this README have been updated to follow this use case.
49
+
If you want to continue logging events to a single Amplitude App (and a single API key), then you will want to call functions on the `default instance`, which you can fetch by calling `amplitude.getInstance()` with no instance name. The code examples in this README have been updated to follow this use case.
50
50
51
-
For example, if you wanted to initialize the SDK with your apiKey and log an event, you would do something like this:
51
+
For example, if you wanted to initialize the SDK with your single apiKey and log an event, you would do something like this:
52
52
53
53
```javascript
54
54
amplitude.getInstance().init('API_KEY');
@@ -65,7 +65,7 @@ app.logEvent('EVENT_NAME');
65
65
66
66
### Backwards Compatibility ###
67
67
68
-
Most people upgrading to v3.0.0 will continue logging events to a single Amplitude app. To make this transition as smooth as possible, we try to maintain backwards compatibility for most things. All of the *public* methods of `amplitude` should still work as expected, as they have all been mapped to their equivalent on the default instance.
68
+
Most people upgrading to v3.0.0 will continue logging events to a single Amplitude app. To make this transition as smooth as possible, we try to maintain backwards compatibility for most things. All of the existing event data, existing settings, and returning users (users who already have a deviceId and/or userId) will stay with the `default instance`. All of the *public* methods of `amplitude` should still work as expected, as they have all been mapped to their equivalent on the default instance.
69
69
70
70
For example `amplitude.init('API_KEY')` should still work as it has been mapped to `amplitude.getInstance().init('API_KEY')`.
71
71
@@ -79,37 +79,33 @@ Likewise `amplitude.logEvent('EVENT_NAME')` should still work as it has been map
79
79
80
80
If you want to log events to multiple Amplitude apps, you will want to use separate instances for each Amplitude app. As mentioned earlier, each instance will allow for completely independent apiKeys, userIds, deviceIds, and settings.
81
81
82
-
You will need to assign a name to each Amplitude app / instance, and use that name consistently when fetching that instance to call functions. You could use names such as `app1`, `app2`, or more descriptive names such as `prod_app`, `test_app`. Note these names do not need to correspond to the names of your apps in the Amplitude dashboards. The only thing that matters is that each instance is initialized with the correct apiKey.
82
+
You will need to assign a name to each Amplitude app / instance, and use that name consistently when fetching that instance to call functions. **IMPORTANT: Once you have chosen a name for that instance you cannot change it.** Every instance's data and settings are tied to its name, and you will need to continue using that instance name for all future versions of your app to maintain data continuity, so chose your instance names wisely. Note these names do not need to correspond to the names of your apps in the Amplitude dashboards, but they need to remain consistent through your code. You also need to be sure that each instance is initialized with the correct apiKey.
83
83
84
-
Here's an example of how to set up and log events to two separate apps:
84
+
Instance names must be nonnull and nonempty strings. You can fetch each instance by name by calling `amplitude.getInstance('INSTANCE_NAME')`.
85
85
86
+
As mentioned before, each new instance created will have its own apiKey, userId, deviceId, and settings. **You will have to reconfigure all the settings for each instance.** This gives you the freedom to have different settings for each instance.
87
+
88
+
### Example of how to Set Up and Log Events to Two Separate Apps ###
amplitude.getInstance('new_app').logEvent('Viewed Home Page');
98
+
amplitude.getInstance().identify(identify);
99
+
amplitude.getInstance().logEvent('Viewed Home Page');
96
100
```
97
101
98
-
**IMPORTANT - Upgrading from single app to multiple apps:** if you were tracking users with a single app before v3.0.0, you might be wondering what will happen to returning users (users who already have a deviceId and/or userId). By default any instance you initialize will inherit existing deviceId and userId values from before v3.0.0. This will maintain continuity in your existing app, and those users will appear as returning users. In your new app they will still appear as new users. If you wish to initialize an instance that does not inherit existing deviceId and userId values from before v3.0.0, you can set config option `newBlankInstance` to `true` during initialization.
102
+
### Synchronizing Device Ids Between Apps ###
99
103
100
-
In the above example, both `original_app` and `new_app` inherit existing deviceId and userId values. Below is an example of how to set up and log events to two separate apps, with `new_app` starting from a clean slate (not inheriting existing deviceId and userId values):
104
+
As mentioned before, each instance will have its own deviceId. If you want your apps to share the same deviceId, you can do so *after init* via the `getDeviceId` and `setDeviceId` methods. Here's an example of how to copy the existing deviceId to the `new_app` instance:
0 commit comments