> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/analytics/custom-event.md). # Custom Event ## Prerequisites * At least one supported analytics provider must be configured: [AppsFlyer](/natively-platform/features/analytics/appsflyer.md) or [Facebook](/natively-platform/features/analytics/facebook.md). ## Implementation Choose your integration method below: **Bubble.io Plugin** (No-Code), **JavaScript SDK** (Code), or **AI Agents** (for AI-powered editors like Lovable, Base44, and Replit). ### Initialization {% tabs %} {% tab title="Bubble.io Plugin" %} **Check Plugin** Before starting, verify if the Natively plugin is already installed in your Bubble project. 1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar. 2. **Check Installed Plugins:** Look through your list of installed plugins for "Natively iOS & Android app builder". * If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

* If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

{% endtab %} {% tab title="JavaScript SDK" %} **Check SDK** Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase. 1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `` section. 2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`). ```javascript ``` {% hint style="info" %} To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number. {% endhint %} {% endtab %} {% tab title="AI Agents" %} **Initialize the SDK** AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project. Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project. ``` Check if the following Natively SDK script is present in the of index.html. If missing or outdated, add it: For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases ``` {% endtab %} {% endtabs %} ### Setup Logic {% tabs %} {% tab title="Bubble.io Plugin" %} ### \[Action] Natively - Send Custom Event * **Event name** - the identifier that will appear in your provider's dashboard (e.g. `user_onboarded`, `checkout_started`). * **Event data** - a JSON object containing custom parameters and values to send with the event.

{% endtab %} {% tab title="JavaScript SDK" %} ```javascript // ============================================================================ // NATIVELY ANALYTICS SDK - DOCUMENTATION & EXAMPLES // ============================================================================ // No initialization required — analyticsTrackEvent is available directly // on the global window.natively object. // ============================================================================ // ALL AVAILABLE METHODS // ============================================================================ // window.natively.analyticsTrackEvent(name, data) // - Logs an analytics event with optional event data. // - Forwarded to your configured provider: AppsFlyer or Facebook. // - name: string — the event identifier // - data: object — plain JS object of custom parameters and values. Optional. // --- Custom Event. Example. Start --- const eventData = { user_id: "12345", screen: "home", duration_seconds: 45, is_premium_user: true, }; window.natively.analyticsTrackEvent("button_clicked", eventData); // --- Custom Event. Example. End --- ``` {% endtab %} {% tab title="AI Agents" %} AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Copy the line below and paste it into your AI agent.

[Your feature description] using the Natively Analytics SDK: window.natively.analyticsTrackEvent(name, data) logs an analytics event, forwarded to your configured provider (AppsFlyer or Facebook) — name: string, the event identifier; data: plain object, optional, custom parameters and values. No callback required. For reference: https://docs.buildnatively.com/natively-platform/features/analytics/custom-event

{% hint style="warning" %} Replace the placeholder at the beginning with a description of what you want to build - for example: "Track a custom event when the user completes onboarding, including their user ID and signup method". {% endhint %} {% endtab %} {% endtabs %} ### How to use #### Use event names that match your provider's conventions AppsFlyer and Facebook both expect consistent, descriptive event names - stick to `snake_case` or a naming scheme you use consistently across your app (e.g. `signed_up`, `completed_purchase`, `viewed_product`), so events are easy to filter and analyze in your provider's dashboard. #### Only include data relevant to that event `data` accepts any plain object, but keep it scoped to what actually describes the event - a `checkout_started` event might include `cart_value` and `item_count`, but doesn't need unrelated user profile data. #### Track key user milestones, not every interaction Custom events are most useful for meaningful actions - signups, purchases, feature adoption - rather than logging every tap or scroll, which adds noise without improving attribution or analysis. #### Combine with In-App Purchases tracking; don't duplicate it If you have In-App Purchases enabled, AppsFlyer already tracks purchases automatically - you don't need a custom event for that. Use custom events for everything else: onboarding steps, feature usage, engagement milestones. ## Testing {% tabs %} {% tab title="AppsFlyer" %} 1. Add your test device to your AppsFlyer account. See [AppsFlyer's Registering test devices](https://support.appsflyer.com/hc/en-us/articles/207031996-Registering-test-devices#register-a-device-manually). 2. In the AppsFlyer dashboard, go to **Settings** > **SDK Integration Test** > **Live Events**. 3. Select your app and your test device, then click **Continue**. 4. Click **Start** to begin listening for live events. 5. Launch the app on your test device and trigger the custom event you want to test (e.g., tap the button that calls `analyticsTrackEvent`). 6. Check the **Live Events** dashboard - your event and its associated data should appear there in real time.

{% endtab %} {% tab title="Facebook" %} 1. Go to your app's [Events Manager](https://business.facebook.com/events_manager) in Meta Business Suite, and select **Test Events**. 2. Pair your test device - Facebook provides a QR code or pairing code to scan/enter on the device running your app. 3. Launch the app on your test device and trigger the custom event you want to test. 4. Check the **Test Events** dashboard for your event and its parameters. {% hint style="info" %} Event delivery timing can vary - some events appear within seconds, though Facebook's own documentation notes it can take up to 30 minutes in some cases. {% endhint %} For the full setup process, see [Meta's App Events documentation](https://developers.facebook.com/docs/app-events/overview/). {% endtab %} {% endtabs %} ## Troubleshooting

Custom event doesn't appear in AppsFlyer's Live Events

Confirm you clicked **Start** on the SDK Integration Test page before triggering the event - Live Events only captures events sent after listening has started. Also confirm the app has been rebuilt after enabling AppsFlyer.

Custom event doesn't appear in Facebook's Test Events

Confirm your test device is correctly paired via the QR code or pairing code. Delivery timing can vary - allow up to 30 minutes before assuming it failed, per Facebook's own documentation.

The event appears, but without the expected data

`data` is a plain JavaScript object, not `undefined`, `null`, or a non-serializable value. Check the [Debug Console](/guides/integration/debug-console.md) to see exactly what payload was sent.

Event name doesn't show up as expected in the dashboard

Some providers cap the number of distinct event names (e.g. Facebook allows up to 1,000) - reusing a small, consistent set of event names is safer than generating dynamic ones per event.

Not working in a web browser or the Natively Preview app

This is a native feature and does not work in a standard web browser or in the Natively Preview app. Test on a real device using a full Natively build.

[^1]: Replace this placeholder