This article will help you:
- View and understand the behavior of your users across multiple products
- Reconcile users with multiple user IDs across your products
With Amplitude's Portfolio add-on, you can easily generate a holistic view of how your users interact with your entire product portfolio. If you've instrumented multiple platforms or product lines, Portfolio can give you unparalleled insight into your users’ complete journey.
NOTE: This feature is available to customers on the Growth or Enterprise plan who have purchased the Portfolio add-on. Also, you should be sure to understand project settings within Amplitude before getting started.
How it works
The foundation of Portfolio's ability to create cross-product analyses is the View. Views are collections of Amplitude Projects or data sources that consolidate the goings-on in each project into a single display. A View can be a collection of one or more data sources, each allowing you to analyze users across multiple projects at once.
NOTE: Views cannot ingest data themselves, but you can change and update them at any point.
Portfolio looks at your users across the entire organization, instead of siloing them on the basis of individual projects. Amplitude assumes that if it sees the same user ID (or device ID) in different projects, they're attached to the same user.
However, user properties are siloed on a per-project basis: User properties on events triggered in a particular project will be the user property values for that project, and that project only. As an example, assume you have two projects iOS and Android. The user example@amplitude.com
has a user property called Version
, with a value of 1.0 in the iOS project and a value of 2.0 in the Android project. In this case, events triggered by this user in the iOS project will have the value of Version
set to 1.0, and events triggered in the Android project will have the value of Version
set to 2.0.
NOTE: If an event type has the same name on two or more projects, it will be considered the same event in the dropdown.
While cohort export for portfolio projects is supported for all destinations, when you select Amplitude User Property, only device_id
and user_id
will be available.
Create a Portfolio view
Admins and managers in an organization can access and create the Portfolio view by clicking and navigating to Organization settings > Projects > Create Portfolio View. A modal will appear; in it, you can name the portfolio view and set user permissions.
At this point, you'll be able to connect multiple projects into this cross-project view. Just click Update Source Projects to select the projects that should be consolidated into a single view.
User mapping (aliasing)
It's not uncommon for user IDs for the same user to differ across projects within the same organization. The User Mapping API endpoint allows you to merge two users together who would otherwise be tracked by different user IDs in Amplitude. Note that this cannot be done through the UI, and is only available as an API call.
In the example below, three user records—each with a different users ID—are all merged into the user ID mike@hooli.com
. This new user ID will be that user’s “global” user ID in the cross-project view. This way, you can get an accurate count of the number of unique users across your entire product portfolio.
When users are mapped, user properties are not merged—this means the user properties attached to each event will be those from the original user who triggered the event in the first place.
You can access the current API endpoint by sending a POST or GET request to https://api.amplitude.com/usermap, with two request parameters:
- api_key: an API Key for any project (data source) in your organization
- mapping: Either a single JSON mapping object or an array of JSON objects, each of which represents a single mapping
A mapping alias must have a user_id
key. If unmap
is set to True
, then there cannot be a global_user_id
. Otherwise, there must be a global_user_id
:
- user_id (string): Required. A UUID (unique user ID) specified by you. This is the user who will be mapped. Note that only one
user_id
can be mapped at a time. - global_user_id (string): Required unless
unmap
is true. A UUID (unique user ID) specified by you. This should be the unified identity the otheruser_id
will map into. - unmap (boolean): If true, the current mapping for
user_id
will be removed.
User mapping example
curl --data 'api_key=YOUR_API_KEY' --data mapping='[{"user_id":"63629@hmail.com", "global_user_id": "mike@hooli.com"}]' https://api.amplitude.com/usermap
Here, user 63629@hmail.com
will be merged into mike@hooli.com
.
User unmapping example
curl --data 'api_key=YOUR_API_KEY' --data mapping='[{"user_id":"63629@hmail.com", "unmap": true}]' https://api.amplitude.com/usermap
Here, user 63629@hmail.com
will be un-merged from the canonical user (previously set as mike@hooli.com
).