> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Push notifications

> Learn how to send template-based push notifications from key triggers with Trophy.

> [!NOTE]
>
> These are Trophy's legacy, template-based push notifications, sent from fixed triggers. For users in the [agentic messaging](/agentic-messaging/overview.md) cohort, agentic messaging replaces them: lifecycle agents write and send personalized push notifications instead. The push channels set up on this page are shared by both. See [agentic messaging channels](/agentic-messaging/channels.md).

Trophy can send automated push notifications to users based on key triggers without requiring any code. Here we’ll look at what these triggers are, and how they can help bring users back to your product.

## Types of push notifications

Trophy supports 4 types of push notifications, each of which is designed to suit a common engagement scenario.

All push notifications are optional, but all four can be used simultaneously and can be controlled from the [Push Notifications](https://app.trophy.so/push/configure) page in the Trophy dashboard.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/push_notification_types.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=10e87e627e9427358a53321380ba970e" />

* **Milestone notifications** are sent to users each time they complete a [Milestone](/features/milestones.md).
* **Recap notifications** are sent to users on a pre-defined frequency to summarize progress. Recap notifications can be configured to be sent daily, weekly, monthly or yearly depending on your use case.
* **Reactivation notifications** are sent to users after they become inactive with the goal of bringing them back to your app.
* **Streak notifications** are automatically sent to users reminding them to extend their [Streak](/features/streaks.md).

## Supported channels

Trophy supports sending push notifications using 3 channels which can all be configured on the [Channels](https://app.trophy.so/push/channels) page of the Trophy dashboard.

### Apple Push Notification Service (APNs)

Trophy supports sending push notifications to users via APNs through a certificate-based connection.

To send push notifications using APNs, you'll need to provide Trophy with the following credentials from your Apple Developer Account:

* **APN Signing Key**: Trophy uses this to securely send notifications via APNs
* **Team ID**: The team ID of your Apple Developer Account
* **Key ID**: The ID of your APNs authentication key
* **Bundle ID**: Your app's unique bundle identifier

> [!NOTE]
>
> For more information on how to configure certificate-based connection to APNs
> from a third-party service, read the [official setup
> guide](https://developer.apple.com/documentation/usernotifications/establishing-a-certificate-based-connection-to-apns).

### Firebase Cloud Messaging (FCM)

Trophy supports sending push notifications to users via FCM. To achieve this you'll need to provide Trophy with your Firebase Service Account JSON in the following format:

```json FCM Service Account JSON theme={null}
{
  "type": "service_account",
  "project_id": "XXX",
  "private_key_id": "XXX",
  "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n",
  "client_email": "XXX@XXX.com",
  "client_id": "XXX",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/XXX"
}
```

> [!NOTE]
>
> For more information on Firebase service accounts and how to authenticate
> external services to use FCM, read the [official service accounts
> guide](https://firebase.google.com/support/guides/service-accounts).

### Expo Push Service

Trophy supports sending push notifications to users via Expo Push Service.

Expo Push Service saves you having to integrate with FCM and APNs individually and automatically directs notifications through the relevant service based on your users platform.

To achieve this you must provide Trophy with a few key details from your Expo account:

* **Expo Project Name**: The name of your Expo project
* **Expo Push Token**: Your authentication token for sending notifications via Expo (required if using [enhanced security](https://docs.expo.dev/push-notifications/sending-notifications/#additional-security)).

> [!NOTE]
>
> For more information on Expo Push Service and how to authenticate external
> providers, see the [official
> guide](https://docs.expo.dev/push-notifications/sending-notifications).

## Sending push notifications

Follow the steps below to start sending push notifications using Trophy.

> [!TIP]
>
> Users can control which push notifications they receive through Trophy's [user
> preferences API](/features/users.md#notification-preferences). This allows you to
> build a preference center in your application where users can opt in or out of
> specific notification types.

**1. Set up channels**

Trophy support sending push notifications via 3 channels, [Apple Push Notification Service (APNs)](#apple-push-notification-service-apns), [Firebase Cloud Messaging (FCM)](#firebase-cloud-messaging-fcm) or [Expo Push Service](#expo-push-service).

Head into the [channels page](https://app.trophy.so/push/channels) of the Trophy dashboard and configure your preferred channel by following the dedicated guides above.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/push_channels.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=7b6f01417e9d1ef57134cad3335ce9a6" />

**2. Add templates**

Trophy provides a default template for each [type of push notification](#types-of-push-notifications) that Trophy supports.

On the [configure page](https://app.trophy.so/push/configure), each notification type has its own section. Add templates under the relevant type.

Follow the guide on [designing push notifications](#designing-push-notifications) to learn more.

![](https://mintcdn.com/trophy-cep/KNKynR4KUMaS-uCh/assets/features/push/create_push_template.png?fit=max\&auto=format\&n=KNKynR4KUMaS-uCh\&q=85\&s=f5c33beac851a706d3e1012bfb40d6e5)

**3. Associate device tokens**

To send notifications to users, Trophy needs to know the unique tokens assigned to their devices. You tell Trophy about devices by associating device tokens with each user you identify.

Trophy will use the device tokens you associate with each user when communicating with supported [push notification channels](#supported-channels) to route notifications to the correct device.

To associate a device token with a user in Trophy, either assign `deviceTokens` when [identifying users explicitly](https://docs.trophy.so/api-reference/endpoints/users/identify-a-user#body-device-tokens), or when [sending metric events](https://docs.trophy.so/api-reference/endpoints/events/submit-a-metric-event#body-user-device-tokens).

Here's how to associated device tokens when identifying users:

```bash cURL {10} theme={null}
curl --request PUT \
  --url https://app.trophy.so/api/users/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "email": "user@example.com",
  "name": "User",
  "tz": "Europe/London",
  "subscribeToEmails": true,
  "deviceTokens": ["token1", "token2"]
}'
```

```typescript Node {6} theme={null}
trophy.users.identify("user-id", {
  email: "user@example.com",
  name: "User",
  tz: "Europe/London",
  subscribeToEmails: true,
  deviceTokens: ["token1", "token2"],
});
```

```python Python {7} theme={null}
client.users.identify(
    id="user-id",
    email="user@example.com",
    name="User",
    tz="Europe/London",
    subscribeToEmails=True,
    deviceTokens=["token1", "token2"],
)
```

```php PHP {6} theme={null}
$trophy->users->identify("user-id", [
    'email' => 'user@example.com',
    'name' => 'User',
    'tz' => 'Europe/London',
    'subscribeToEmails' => true,
    'deviceTokens' => ['token1', 'token2'],
]);
```

```java Java {6} theme={null}
UpdatedUser user = UpdatedUser.builder()
    .email("user@example.com")
    .name("User")
    .tz("Europe/London")
    .subscribeToEmails(true)
    .deviceTokens(Arrays.asList("token1", "token2"))
    .build();

client.users().identify("user-id", user);
```

```go Go {8} theme={null}
response, err := client.Users.Identify(
    "user-id",
    &api.UpdatedUser{
        Email:            "user@example.com",
        Name:             "User",
        Tz:               "Europe/London",
        SubscribeToEmails: true,
        DeviceTokens:     []string{"token1", "token2"},
    },
)
```

```csharp C# {6} theme={null}
var user = new UpdatedUser {
    Email = "user@example.com",
    Name = "User",
    Tz = "Europe/London",
    SubscribeToEmails = true,
    DeviceTokens = new[] { "token1", "token2" }
};

await trophy.Users.IdentifyAsync("user-id", user);
```

```ruby Ruby {7} theme={null}
result = client.users.identify(
  "user-id",
  :email => "user@example.com",
  :name => "User",
  :tz => "Europe/London",
  :subscribeToEmails => true,
  :deviceTokens => ["token1", "token2"]
)
```

And here's how to associate device tokens when sending metric events:

```bash cURL {10} theme={null}
curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London",
    "deviceTokens": ["token1", "token2"]
  },
  "value": 750
}'
```

```typescript Node {6} theme={null}
trophy.metrics.event("flashcards-flipped", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
    deviceTokens: ["token1", "token2"],
  },
  value: 750,
});
```

```python Python {7} theme={null}
client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
        deviceTokens=["token1", "token2"],
    ),
    value=750.0,
)
```

```php PHP {6} theme={null}
$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com',
    'deviceTokens' => ['token1', 'token2'],
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 750
]);

$trophy->metrics->event("flashcards-flipped", $request);
```

```java Java {6} theme={null}
MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .deviceTokens(Arrays.asList("token1", "token2"))
          .build()
      )
      .value(750)
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);
```

```go Go {8} theme={null}
response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
            DeviceTokens: []string{"token1", "token2"},
        },
        Value: 750,
    },
)
```

```csharp C# {6} theme={null}
var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com",
   DeviceTokens = new[] { "token1", "token2" }
};

var request = new MetricsEventRequest {
   User = user,
   Value = 750
};

await trophy.Metrics.EventAsync("flashcards-flipped", request);
```

```ruby Ruby {7} theme={null}
result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com',
    :deviceTokens => ['token1', 'token2']
  },
  :value => 750
)
```

> [!TIP]
>
> Each user can have multiple device tokens associated with them, to support users who use multiple devices.

**4. Activate templates**

The last step is to activate a template within each [type of push notification](#types-of-push-notifications) section that you want to send.

On the [configure page](https://app.trophy.so/push/configure), activate one template in each type section you want to enable. Once activated, Trophy will start sending push notifications automatically.

> [!TIP]
>
> Users can control which push notification types they receive through Trophy's [user preferences API](/features/users.md#notification-preferences). When a user has disabled a notification type in their preferences, Trophy will respect that setting and won't send those notifications to that user.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/activating_templates.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=9bd6910732be578675eeada68c9cd063" />

## Designing push notifications

By default, Trophy provides a template for each [type of push notification](#types-of-push-notifications) as a good starting point. The default templates can’t be changed, but you can duplicate and customize these as you wish.

> [!TIP]
>
> You can also create blank templates if you just want to start from scratch.

### Template structure

Each push notification has a title and body, and Trophy's no-code push notification template editor allows you to fully customize both fields.

![](https://mintcdn.com/trophy-cep/KNKynR4KUMaS-uCh/assets/features/push/push_template_editor.png?fit=max\&auto=format\&n=KNKynR4KUMaS-uCh\&q=85\&s=e62f3987cfb30f5a84580f8c7c4f2cb2)

### Using variables

Trophy provides an expansive set of variables that can be used to insert highly relevant and personalized data into your push notifications.

Variables can be inserted by typing `@` in the title or body of any push notification, and searching for your chosen variable.

This will open up the variable editor window where you can configure variables as in the demo below. You can also test different variable values and how your template behaves in different scenarios by using the preview sidebar.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/push_variables.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=c0b1c407ef6c56888e4b65af0e8c8da0" />

### Using variations

Variations can be used to add randomness to the title and body of push notifications sent by Trophy. This prevents notifications from getting boring and helps improve engagement rates.

At send time, Trophy automatically picks one of your variations of the title and body at random and sends the notification to the user.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/push_variations.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=510c6ffd043614f294c339d033397e0e" />

### Using conditions

Trophy's push notification template builder supports using conditions to send different content to each recipient based on their unique context.

All [template variables](#using-variables) can be used in conditions to control what content is used in the title and body of notifications sent by Trophy.

At send time Trophy computes all conditions using each recipients unique context, delivering highly personalized and relevant notifications to each user.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/push/push_conditions.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=822523984ad541ed4a5f511ab935b525" />

## Get support

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.