🕵️Custom Event

Send a custom event with optional data to your configured Analytics provider - AppsFlyer or Facebook.

Prerequisites

At least one supported analytics provider must be configured: AppsFlyer or Facebook.

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

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
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.

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.
Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.26.0).

<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>

To ensure you are using the most up-to-date version, check the Natively GitHub releases page for the latest version number.

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 <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases

Setup Logic

[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.

// ============================================================================
// 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 ---

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

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".

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

Add your test device to your AppsFlyer account. See AppsFlyer's Registering test devices.
In the AppsFlyer dashboard, go to Settings > SDK Integration Test > Live Events.
Select your app and your test device, then click Continue.
Click Start to begin listening for live events.
Launch the app on your test device and trigger the custom event you want to test (e.g., tap the button that calls analyticsTrackEvent).
Check the Live Events dashboard - your event and its associated data should appear there in real time.

Go to your app's Events Manager in Meta Business Suite, and select Test Events.
Pair your test device - Facebook provides a QR code or pairing code to scan/enter on the device running your app.
Launch the app on your test device and trigger the custom event you want to test.
Check the Test Events dashboard for your event and its parameters.

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.

For the full setup process, see Meta's App Events documentation.

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 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.

PreviousFacebook NextBottom Bar

Last updated 20 days ago