---
title: "Events and triggers"
description: "Start Experiences from app events and measure their outcomes."
search:
  tags: ["Features"]
  keywords: ["trigger event", "attribution window", "segment trigger"]
---

Triggers let you show an Experience at the right moment in your app. You can start onboarding when an account is created, offer an upgrade when someone reaches a limit, or follow up when a customer joins a Segment.

The trigger works with your audience and re-entry settings: it tells Nuxie when to start, while those settings decide who receives the Experience and how often they can return. You can also set a goal to measure what they do afterward.

<span id="pick-the-moment-in-your-app" />

## Trigger event

Select the entry point and set **Trigger → Type** to **Event**. Enter the event your app will send, such as `export_limit_reached` for a paywall or `account_created` for onboarding. Use that exact name in [your integration](/docs/sdks).

You can also use supported SDK lifecycle events. For example, `$app_opened` lets the Experience start when the app comes to the foreground.

Give your own app events names without a `$` prefix. Nuxie uses that prefix for its [system events](/docs/api-reference/system-events).

<span id="track-other-app-behavior" />

## Event properties

Event properties add context to an occurrence. A `workout_completed` event could include the duration and workout type. You can record these events for [analytics](/docs/guides/measurement) even when they don't trigger an Experience.

You can also use properties to narrow a trigger. For example, ask Nuxie to start an Experience on `export_requested` only when `format` is `pdf`. The same event sent with another format won't start that Experience. The event name and property values need to match what your app sends.

Properties on an event describe that occurrence. [Customer properties](/docs/guides/customer-properties) describe the person's current state, such as their language or account tier.

## Other trigger types

### Joining or leaving a Segment

Choose **Joins segment** or **Leaves segment** to start an Experience when a customer's membership changes. Selecting either opens a request to Nuxie so it can configure the Segment. For example:

> Start this Experience when a customer joins the Inactive subscribers Segment.

The trigger needs a new entry or exit. Remaining in the Segment doesn't repeatedly start new Journeys.

### Server events

Choose **Server event** to start from an event supplied by a connected service. Nuxie opens a request where you can describe the event, then configures the connected trigger.

A server event can start work while the app is closed. Any device screens run when the customer's app can present them.

### API calls

Choose **API call** when your backend should start the Experience for a customer, such as when a generated report is ready. Publish the Experience, then call its start endpoint from your server.

Use a secret [workspace API key](/docs/api-reference/rest-api#workspace-authentication) and keep it on your server. This endpoint requires workspace API access; the SDK's publishable `pk_` keys don't authenticate it.

```bash
curl -X POST 'https://api.nuxie.ai/v1/experiences/EXPERIENCE_ID/start' \
  -H "Authorization: Bearer $NUXIE_WORKSPACE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'X-Nuxie-Env: test' \
  -H 'Idempotency-Key: report-ready-42' \
  -d '{
    "app_id": "APP_PLATFORM_ID",
    "distinct_id": "customer-123",
    "context": { "report_id": "report-42" }
  }'
```

Use the published Experience's ID, your app platform's `id` from `GET /v1/apps`, and the same customer ID your SDK uses. `context` is optional data for this start. The example targets the test environment; use `X-Nuxie-Env: live` for production. Omitting that header defaults to live.

Reuse the same `Idempotency-Key` when retrying this start, and use a new one for a separate occurrence. Without it, each request gets a new key.

The `202` response includes `journey_id` and a `status`: `started` creates a Journey, `coalesced` reuses an existing Journey, and `ineligible` means the customer didn't meet the entry conditions. A Journey starting doesn't confirm that a screen appeared; device screens run when the customer's app can present them.

<span id="combine-the-event-with-targeting" />

## Audience

Use [Customer properties](/docs/guides/customer-properties) and [Segments](/docs/guides/segments) to choose who receives the Experience. A trigger can occur for many customers while only some belong in the audience.

For example, an export-limit event could start a paywall for free customers while leaving customers with unlimited exports out. Nuxie checks the audience and re-entry rules before starting their Journey.

## Re-entry

Choose **One time** when each customer should enter once, such as an introduction to your app. **Every match** allows a later qualifying trigger to start another Journey. **Once per window** leaves a configured interval between entries, which is useful for an offer or reminder you don't want to repeat too often.

Frequency counts Journeys that started, even if the customer later dismisses or exits. Publishing an update doesn't reset those previous entries.

Set the interval for **Once per window** in the Experience settings. [Eligibility and re-entry](/docs/guides/eligibility-and-reentry) covers the units and active Journeys.

## Conversion goals

A conversion goal measures the outcome you want the Experience to help produce. Choose an event, with optional property conditions, or choose entry into or exit from a Segment. Then set the time window in which it should count.

For a subscription offer, the goal could be a successful payment for the relevant Product. A trial start and a payment are different outcomes, and restoring an existing purchase doesn't count as a new subscription.

For onboarding, use an event your app sends after setup is complete. Submit any collected responses before sending it. For a permission request, send the goal event after the customer grants the permission.

Goals are optional. An Experience without one still reports views, interactions, and exits.

### Conversion window

The conversion window starts when the first screen appears, or when the Journey starts if it has no screens. Each Journey can convert once.

The window stays open until its end even if the customer dismisses, skips, or completes the Experience. That lets you count a matching outcome that happens later, such as a subscription purchased after the customer leaves the paywall.

A Segment goal needs a new entry or exit. Someone who already belongs to the Segment hasn't achieved a goal for joining it.

When Nuxie can link the event directly to a matching Journey within its window, it credits that Journey. Otherwise, it credits the most recently shown Experience whose goal matches and whose conversion window is still open.

## Exit behavior

Enable **exit on goal** if reaching the goal should stop later parts of the Journey. The screen sequence already running continues until it finishes, so any thank-you or setup steps you've included can still run.

With exit on goal disabled, the Journey continues after conversion. To close the screens, add a **Dismiss** step to the [flow on the Canvas](/docs/guides/screens-and-interactions).

Afterward, the customer can return on a later trigger if your audience and re-entry settings allow it.

## Offer eligibility

Offer eligibility helps you avoid selling customers access they already have. Nuxie checks the access being offered before showing it and before checkout. For an upgrade, it checks the higher tier.

Choose what the Experience should do when the customer already has access or when their access can't be confirmed. Nuxie uses their current access and verified purchases on the device. Skipping an offer for an existing subscriber doesn't record a new conversion.

If access can't be confirmed, you can skip an optional offer or show a retry option. Keep the protected capability locked until access is confirmed.

<span id="send-a-trigger-with-your-sdk" />

## SDK integration

Once you've [set up the SDK](/docs/get-started/quickstart), send the trigger from the matching action in your app. Choose your platform below to see the call. These examples use `integration_test`; replace it with your Experience's event name.

**Choose SDK**

Choose your SDK in the sidebar or here to see the call.

**iOS**

```swift
import Nuxie

NuxieSDK.shared.trigger("integration_test")
```

**Android**

```kotlin
import ai.nuxie.sdk.Nuxie

Nuxie.trigger("integration_test")
```

**React Native**

```typescript
import { nuxie } from '@nuxie/react-native';

await nuxie.trigger('integration_test');
```

**Flutter**

```dart
await nuxie.trigger('integration_test');
```

**Unity**

```csharp
await Nuxie.Client.TriggerAsync("integration_test");
```

**Godot**

```gdscript
var result: NuxieResult = await Nuxie.trigger("integration_test")
if not result.ok:
    push_error(result.error.message)
```

**Unreal**

```cpp
Nuxie->Trigger(
    TEXT("integration_test"),
    FNuxieProperties{},
    FNuxieCompletion::CreateLambda([](const FNuxieResult& Result) {
        if (!Result.IsSuccess()) {
            // Surface Result.GetError() through your game's error UI.
        }
    })
);
```

Use the client configured in your SDK integration. Sending the event starts the Experience when the customer matches its audience and re-entry settings.