Portfolio by Amplitude allows users to get a holistic view of their product portfolio and to understand the behaviors of your Users across multiple products. Whether you have instrumented multiple platforms or product lines independently, Portfolio allows you to understand your Users’ complete journey.
Prerequisites
- This feature is available to customers on the Growth or Enterprise plan who have purchased the Portfolio add-on
- Understand the Project Settings settings within Amplitude
Table of Contents
- Create a Portfolio View
- Portfolio Views
- User Merging
- User Properties
- User Mapping (Aliasing)
- Cross-project Events
Create a Portfolio View
To start with understanding your customer's journey across all your projects, you will need to create the Portfolio View which connects these projects together into a single view within Amplitude.
Admins and Managers can access and create the Portfolio view by navigating to Settings --> Projects --> Create Portfolio View. A modal will appear where you can name the portfolio view and set user permissions.
Once a Portfolio View has been created, you'll be able to connect multiple projects into this cross-project view. On this page, click Update Source Projects to select the projects that should be consolidated into a single view.
Portfolio Views
Views are collections of Amplitude Projects or data sources. Views cannot ingest data themselves but can be changed and updated at any point in time. A View can be a collection of one or more data sources, and allows you to analyze users across multiple projects once.
User Merging
With Portfolio, Users are merged across the entire Organization, not individual Projects. This means that if a user has the same User ID, or the same Device ID across multiple projects, we consider that User to be the same.
User Properties
User properties for users are currently not shared or synced across projects within an organization. This means User properties on events performed in a particular project will be the User property values for that project. For example, if you have two projects iOS and Android, and for the user “example@amplitude.com” a User Property called Version is 1.0 on iOS and 2.0 on Android, the events performed in the iOS project by “example@amplitude.com” will have the Version = 1.0, and the events performed by “example@amplitude.com” in the Android project will have Version = 2.0
User Mapping (Aliasing)
Often times, various Projects instrumented in Amplitude don’t use the same User ID between those projects. User Mapping is an API endpoint that allows Organizations to merge two Users together that would otherwise have different User IDs tracked in Amplitude. Note that this cannot be done through the UI, but is an API call.
In the illustrative example below, 3 Users with different Users IDs 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 allows you to get an accurate count of the number of unique Users across your portfolio, and merge their event timelines in User Activity.
When Users are mapped, User Properties are not merged however, so the User Properties attached to each event, will be the User Properties from the original User that performed the event.
The current API endpoint can be accessed 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 (see below for fields) or an array of JSON objects, each of which represents one 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 that 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 that the other user_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@gmail.com", "global_user_id": "mike@hooli.com"}]' https://api.amplitude.com/usermap
In the above request, user 63629@gmail.com will be merged into mike@hooli.com
User Unmapping Example
curl --data 'api_key=YOUR_API_KEY' --data mapping='[{"user_id":"63629@gmail.com", "unmap": true}]' https://api.amplitude.com/usermap
In the above request, user 63629@gmail.com will be unmerged from the canonical user (previously set as mike@hooli.com)
Cross-project Events
Within a multi-project View, you will have access to all event types that exist across the projects. If an event type has the same name on two or more projects, it will be considered the same event in the dropdown.