Amplitude

Before touching Bubble, collect the three pieces of information you need: your ingestion API key, your secret key, and your project's data residency region. In Amplitude, click your project name in the top-left to open the project switcher, then go to Settings (gear icon) → Projects → select your project → General tab. Copy the API Key (used for event ingestion — this is semi-public) and the Secret Key (used for reading data via the Dashboard REST API — keep this private). Scroll down on the same General tab to the Data Residency section. If it shows 'EU,' you must use EU-region API URLs in Bubble. If it shows 'US' or nothing special, use the standard US URLs. Write down all three values before continuing — you will need them in the next steps. Note: The secret key is only shown once when the project is created for some account types — if you cannot find it, you may need to generate a new one under Security in your project settings.

In your Bubble editor, click the Plugins tab in the left sidebar. Click 'Add plugins', search for 'API Connector' (by Bubble), and install it — it is free. Once installed, you will see 'API Connector' appear in your Plugins list. Click it to open the configuration panel. Click 'Add another API' and name it 'Amplitude Ingestion'. Leave the Authentication dropdown set to 'None or self-handled' (you will put the api_key in the body, not headers). You do not need shared headers for ingestion. Click 'Add another call' under this API group and name it 'Send Events'. Set the request type to POST. In the URL field enter your ingestion endpoint: - US region: https://api2.amplitude.com/2/httpapi - EU region: https://api.eu.amplitude.com/2/httpapi Click 'Add parameter' under the Body section and set the body type to 'JSON body'. In the JSON body field, enter: ```json { "api_key": "<api_key>", "events": [ { "user_id": "<user_id>", "event_type": "<event_name>", "time": <timestamp>, "event_properties": {} } ] } ``` For the api_key field, Bubble will parse this as a dynamic field you can initialize. When you see the field appear below the JSON body editor, check the 'Private' checkbox next to api_key to prevent it from appearing in Bubble's Logs tab — even though it is semi-public, you do not want it logged in plain text. Set the field type to 'Text' and the key name to 'api_key'. For user_id, event_name, and timestamp — these remain as dynamic fields you will populate from Bubble Workflows at runtime. Set each as 'Text' type (timestamp as 'Number'). Change the 'Use as' dropdown to 'Action' since you are triggering this from a Workflow, not fetching data to display. Click 'Initialize call'. In the initialization panel, fill in test values: api_key = your actual Amplitude API key, user_id = 'test-user-123', event_name = 'Test Event', timestamp = 1700000000000 (any Unix timestamp in milliseconds). Click 'Send'. You should see a 200 response with body: `{"code": 200, "events_ingested": 1, "payload_size_bytes": N, "upload_time": N}`. If you see `"events_ingested": 0`, check that event_type is not empty. If you see a network error, double-check you used the correct regional URL.

1{
2  "api_key": "<api_key - Private>",
3  "events": [
4    {
5      "user_id": "<user_id>",
6      "event_type": "<event_name>",
7      "time": <timestamp>,
8      "event_properties": {
9        "plan": "<plan_name>",
10        "source": "<source>"
11      }
12    }
13  ]
14}

Now connect the API Connector call to real user actions in your Bubble app. Open the Workflow editor by clicking 'Workflow' in the top menu bar. You will create Workflow actions that fire the 'Send Events' API Connector call at the right moments. For each key product event, create a Workflow or add a step to an existing Workflow: 1. Click 'Click here to add an event' and select the trigger — for example, 'A Button is clicked' (e.g., your Sign Up button, Purchase button, or a key feature button). 2. Add a new step: click 'Click here to add an action' → Plugins → 'Amplitude Ingestion - Send Events'. 3. In the action's parameter fields, map dynamic values: - api_key: paste your Amplitude API key (this field is Private, so it will not appear in logs) - user_id: Current User's unique ID (use 'Current User' → 'Unique ID' in the dynamic dropdown) - event_name: type the event name in quotes, e.g., 'Sign Up' or 'Purchase Completed' - timestamp: use 'Current date/time' and format it as a Unix timestamp in milliseconds For anonymous users who are not yet logged in, you cannot use Current User's ID. Instead, generate a UUID when the user first visits your app and store it in a browser cookie using Bubble's Toolbox plugin (Run JavaScript action). Pass this stored value as the device_id parameter instead of user_id. You can include both user_id and device_id simultaneously once the user logs in — Amplitude will merge the anonymous and identified event histories. Repeat this for each important event: page views, form submissions, feature interactions, purchases. Good events to track in a typical Bubble SaaS app: 'Page View', 'Sign Up', 'Feature Used', 'Purchase Completed', 'Invitation Sent'. After triggering a few test events, go to Amplitude → User Look-Up (left sidebar) or Events tab → Ingestion Debugger to verify they appear. Events typically appear within 30 seconds in the Ingestion Debugger and within a few minutes in User Look-Up.

To pull analytics data back into Bubble — for admin dashboards, reports, or displaying engagement metrics inside your app — set up a second API Connector group that authenticates using Basic Auth with your API key and secret key. In the API Connector plugin, click 'Add another API' and name it 'Amplitude Dashboard'. Click the Authentication dropdown and select 'HTTP Basic Auth'. In the Username field, enter your Amplitude API key. In the Password field, enter your Amplitude secret key. Check the 'Private' checkbox on both fields — these credentials give read access to your analytics data and must be kept server-side. Click 'Add another call' under 'Amplitude Dashboard' and name it 'Get Event Segmentation'. Set the request type to GET. In the URL field, enter the segmentation endpoint: - US region: https://amplitude.com/api/2/events/segmentation - EU region: https://analytics.eu.amplitude.com/api/2/events/segmentation Add URL parameters (Query Parameters section): - e: the event JSON (e.g., `{"event_type":"Sign Up"}`) - start: start date in YYYYMMDD format (e.g., 20240101) - end: end date in YYYYMMDD format - m: metric type (e.g., 'uniques' for unique users, 'totals' for event counts) - i: interval in days (1 for daily, 7 for weekly, 30 for monthly) Change 'Use as' to 'Data' since you will bind the results to page elements. Click 'Initialize call'. Fill in test values: e = `{"event_type":"Sign Up"}`, start = a date 30 days ago in YYYYMMDD format, end = today's date in YYYYMMDD format, m = 'uniques', i = 1. Click 'Send'. You should receive a JSON response like: ```json { "data": { "series": [[N, N, N, ...]], "xValues": ["YYYY-MM-DD", "YYYY-MM-DD", ...], "seriesCollapsed": [[{"value": N}]] } } ``` Bubble will automatically detect the response structure. If the initialize call fails with 403, verify that your Amplitude plan supports Dashboard REST API access — the secret key and API key must match the project and the plan must include API access.

1GET https://amplitude.com/api/2/events/segmentation
2Authorization: Basic base64(api_key:secret_key)  [handled automatically by API Connector Basic Auth]
3
4Query Parameters:
5  e={"event_type":"Sign Up"}
6  start=20240601
7  end=20240701
8  m=uniques
9  i=1
10
11Response:
12{
13  "data": {
14    "series": [[12, 24, 31, 18, 29, 40, 33]],
15    "xValues": ["2024-06-01", "2024-06-02", "2024-06-03", "2024-06-04", "2024-06-05", "2024-06-06", "2024-06-07"],
16    "seriesCollapsed": [[{"value": 187}]]
17  }
18}

With the Dashboard REST API call initialized, you can now display Amplitude data on Bubble pages. The most common pattern is a Repeating Group that shows a daily event count table, but you can also bind totals to Text elements for summary stats. To display a daily trend table: 1. Add a Repeating Group element to your page. Set 'Type of content' to 'text' (for the date column) — or create a custom data type to hold Amplitude results. 2. The cleaner approach: on page load, run a Workflow that calls 'Amplitude Dashboard - Get Event Segmentation' and stores the results in Custom States on the page. Set up a Custom State of type 'text' (list) for xValues and another Custom State of type 'number' (list) for the series data. 3. In the Workflow action, after the API call, add steps to 'Set state' using the returned data: xValues list → date state, series[0] list → count state. 4. In the Repeating Group, set 'Data source' to the date Custom State list. In the first column, display 'Current cell's text' (the date). In the second column, add a Text element and use 'Parent group's index' to index into the count Custom State list. For a total count display (e.g., 'Total sign-ups this month'), use the seriesCollapsed field — it returns the sum for the period. Add a Text element on your page and in its value, use 'Do a search for' or bind to a Custom State that holds the collapsed total. Important: cache results in the Bubble database when possible. Each API call to Amplitude consumes Workload Units on Bubble's infrastructure. For dashboards viewed frequently, run a scheduled Backend Workflow (paid plan) once per hour to refresh the cached data, and bind page elements to the Bubble database instead of making live API calls on every page load. Add Bubble privacy rules to any data type you create to store Amplitude results — go to Data tab → Privacy → [your data type] → and restrict access to logged-in users or admins only.

Before going live, run a verification pass to confirm everything works end-to-end. Verify event ingestion: 1. Trigger each of your Bubble Workflows that send events (click the buttons, submit the forms, complete the actions in your test environment). 2. In Amplitude, go to Data → Ingestion Debugger (left sidebar under Data). Look for your test events — they should appear within 30 seconds with the correct event_type, user_id, and event_properties. 3. If events appear with `events_ingested: 0` in the API response, check that event_type is not an empty string and that either user_id or device_id is present in every event. 4. If events do not appear in Ingestion Debugger at all despite HTTP 200 responses from the API call, this is the EU region silent failure — go back to your Amplitude project Settings → General → Data Residency and compare to your API Connector URL. Switch to the EU endpoint if needed. Verify Dashboard REST API reads: 1. Open your analytics dashboard page in Bubble's Preview mode. 2. Check that the Repeating Group or Text elements populate with real data. 3. If you receive a 403 error from the Dashboard REST API, verify that your Amplitude plan includes API access. The Starter free plan may restrict Dashboard REST API access — check your plan in Amplitude Settings → Billing. 4. If you receive a 401, double-check that the API key (username) and secret key (password) in the API Connector's Basic Auth settings match the project you are querying. Event taxonomy best practices before launch: - Use consistent event_type naming across all Bubble Workflows: use snake_case or Title Case and stick to one convention ('sign_up' not 'Sign Up' in one place and 'user_signed_up' in another) - Always include user_id for logged-in users — events without user_id cannot be tied to retention or LTV cohorts - Add event_properties that give context: plan name, feature name, source page Check the Bubble Logs tab (Logs → Workflow logs) to confirm API calls are completing without errors and to monitor WU consumption. If you see high WU usage, consider batching multiple events into a single API call using Bubble's 'List of' text constructor to build the events array.