Trigger components

A trigger component is a small Encore entry that sits inside one of your own screens, in the normal flow of your layout. When the user taps it, it opens the reward sheet for its placement: the same sheet show() presents, with the same premium brand offers, each one a real perk a brand funds to acquire customers. Instead of deciding in code when to interrupt the user with the sheet, you place an entry where the reward makes sense and let the user open it when they choose to. You add it with one line and a placement ID. Encore decides how it looks.

Coming soon. Trigger components aren’t in a released SDK yet. This guide describes them as they ship in the next release of each SDK, so you can plan your screens now. Each SDK’s minimum version is listed here once it’s released.

The two trigger components

Trigger component	What it is	Where it goes
Gifts Button	A “you have a gift” entry: a card, an animated gift box, a thank you banner, or a compact pill.	A reward moment, such as the screen after a finished streak, in place of your own `show()` call
Claim Reminder	A card that reminds the user of an offer they claimed but haven’t finished, with a countdown	A screen users return to on their own, such as your home screen

Start with the quickstart: it adds both in a few lines on iOS, Android, React Native, Flutter, and the web. Prefer to draw the entry in your own style? Build your own button: Encore still decides what it shows, counts its views and taps, and opens the reward sheet.

Looks come from Encore

Each trigger component’s look (its layout, copy, colors, and height) is served by Encore, not built into your app. Encore draws it with the same engine that draws the reward sheet. That means:

No app update to change a look. Encore can switch the Gifts Button from the card to the banner, or reword the Claim Reminder, for every user on a version that supports trigger components.
Encore can test looks. Encore picks each trigger component’s look, and can run an experiment comparing looks across your users. See Experiments and looks.
Copy arrives in the user’s language. See Localization.

Your code never builds the entry’s views. You place it and give it a placement. If you like, you also give it your own text and colors.

Your text

Write the entry’s words yourself with headline, subheadline and cta, the same names the reward sheet uses. Anything you leave out, or pass blank, shows the look’s own copy, so you can set just the line you care about:

GiftsButton(placement: "streak")
    .headline("You kept your streak!")
    .subheadline("A gift from us, on the house")
    .cta("Open")

GiftsButton(
    placement = "streak",
    headline = "You kept your streak!",
    subheadline = "A gift from us, on the house",
    cta = "Open",
)

<EncoreGiftsButton
  placement="streak"
  headline="You kept your streak!"
  subheadline="A gift from us, on the house"
  cta="Open"
/>

EncoreGiftsButton(
  placement: 'streak',
  headline: 'You kept your streak!',
  subheadline: 'A gift from us, on the house',
  cta: 'Open',
)

Encore.triggers.giftsButton.mount(element, {
  placement: 'streak',
  headline: 'You kept your streak!',
  subheadline: 'A gift from us, on the house',
  cta: 'Open',
});

<GiftsButton
  placement="streak"
  headline="You kept your streak!"
  subheadline="A gift from us, on the house"
  cta="Open"
/>

Claim Reminder takes the same three. On UIKit and Android Views, set the headline, subheadline and cta properties.

Option	What it replaces
`headline`	The entry’s main line
`subheadline`	The line under it
`cta`	The button’s label

How your text is shown:

Each look has its own default. The copy you fall back to belongs to the look Encore serves, in the user’s language. If Encore tests two looks, each falls back to its own words.
A look shows only the lines it has. Your cta appears on looks that draw a button, and your subheadline on looks that draw a second line. No Claim Reminder look draws a subheadline today. A look with no place for a line keeps its own copy there.
Your text is shown as you pass it. Encore doesn’t translate it, so pass the user’s language yourself if your app has more than one.
One line each, up to 120 characters. Line breaks and invisible control characters are removed. Text with nothing visible left counts as blank.
The thanks look keeps Encore’s words. After a completion, the thanks look shows its own copy even when you pass text.
Screen readers keep the brand. When your headline replaces a Claim Reminder’s title, VoiceOver and TalkBack still read the advertiser’s name.

How it relates to the reward sheet

A trigger component is a way in to the reward sheet, not a second sheet:

It shows only when the reward sheet it opens has offers for this user at this placement. It checks first, so a tap never opens an empty sheet.
A tap opens that sheet exactly as show() would, with the offers it already checked.
publisherReward and onResult work on that sheet as they do for show(). See Pass your prize and read the result.
When the sheet closes, the entry checks again. It stays while offers remain and hides when none are left.

What you can count on

These hold for every trigger component on every platform.

It takes no space when there’s nothing to show

A trigger component is zero height, and never shows an empty or broken entry, until it has something to show. Design every screen that holds one so it looks right both with and without it. Troubleshooting lists every reason it can be empty.

It never crashes your app

A trigger component never throws into your code. A network error, an unknown ID, or a look the SDK can’t draw all end the same way: it renders nothing. A look that uses something your SDK version can’t draw is never drawn partly or wrongly; the entry stays empty instead.

It sizes itself

Its height comes from the look Encore serves, and it reports that height to your layout. Give it the width of your content and leave the height to the trigger component: put it in a stack, column, or list, and use wrap_content on Android Views. See Heights and Width and alignment.

Its text follows the user’s text size

The entry’s text grows with the user’s larger text setting, up to a limit set by the look, so the entry keeps its height. A long line shrinks to fit before it’s cut off.

It keeps itself current

It checks again when your app returns to the foreground and when the sheet it opened closes, and hides when what it showed no longer applies. It reloads when you call identify(), reset(), or setLanguage(), so a new user never sees the previous user’s entry.

Dismissals stay on the device

When a look lets the user dismiss the entry (the Claim Reminder’s ×), the dismissal is stored on that device only. It hides that item on every screen showing the same trigger component. Nothing is sent to your server or changed on the user’s account.

Heights

These are the heights Encore serves today, in points on iOS, dp on Android, and CSS pixels on the web. React Native and Flutter take the iOS or Android value of the device. They’re set by the look, so Encore can change them without an app update.

Trigger component	Look	Height
Gifts Button	`card`	76
Gifts Button	`banner`	88
Gifts Button	`pulse`	112
Gifts Button	`pill`	48
Gifts Button	`offerMarquee`, `offerColumns`, `giftCard` and `stillWaiting`	76
Claim Reminder	`featured`	85
Claim Reminder	Every other look	76

Looks in one experiment can have different heights, so a Gifts Button can change height between users. Leave the height flexible.

Colors

Each trigger component reads these fields from the appearance you pass. That appearance styles only the trigger component, never the sheet it opens: set the sheet’s look where you style your sheets, as you do when you present the sheet yourself.

Field	What it colors	When you leave it out
`backgroundColor`	The entry’s surface	The color order below
`textColor`	Titles and the countdown	The color order below
`accentColor`	Buttons, progress, and highlights	The color order below
`secondaryTextColor`	Subtitles, the countdown’s units, and the close button	Your text color, faded by the look
`trackColor`	The unfilled part of a progress bar	Your text color, faded by the look
`onAccentColor`	Text and icons drawn on the accent	Black or white, whichever reads on the accent. Some looks draw button text in the entry’s background color when that reads too
`backgroundEndColor`	The second color of a look’s background gradient, such as the featured Claim Reminder’s	Your background color, so the entry is solid

For each color on its own, the first one set wins:

Your appearance.
Your app’s theme in the Encore portal. Today this is the accent color you saved for the app.
The look’s own colors, set by Encore.
The built-in default: a dark surface with a gold accent.

A color you set is drawn exactly as you set it. A look can fade its secondary text or its track, but only when you haven’t set that color yourself. Your textColor applies on its own, with or without a backgroundColor. When a background is set without a text color at the same step, the text is black or white, whichever reads on that background. Hex formats are #RGB, #RRGGBB, and #RRGGBBAA. A value that isn’t a hex color is ignored, and the next step in the order applies. On the web, the reward sheet’s other AppearanceConfig fields (headline, claimButton, and the rest) don’t apply to the entry. To change the entry’s words, use headline, subheadline and cta.

Light and dark

colorScheme sets the look’s mode: light, dark, or system, which follows the device. Leave it out and the entry follows the mode you saved for your app in the Encore portal, where auto follows the device. With neither set, the entry is dark. In light mode, the order is your appearance, then your app’s portal theme, then the look’s light colors, then a light default: a white surface with dark text and a gold accent. A look’s dark colors never apply in light mode.

Icon

The icon option picks the icon the look draws. It goes on the trigger component itself, next to placement, not inside appearance:

gift, the default: Encore’s gift.
appIcon: your app’s store icon, from your app’s settings in the Encore portal. When your app has no store icon, the look draws the gift.
none: no icon.

Looks that show the advertiser’s logo keep it whatever you set here.

Width and alignment

A trigger component is never wider than its look. Encore sets that width for each look. In a container narrower than the look, such as a phone screen, it fills the container. In a wider one, such as a large screen or a desktop page, it keeps the look’s width and sits where alignment puts it:

center, the default.
leading: the start of the line in your app’s writing direction (left in English, right in Arabic).
trailing: the end of the line.

alignment goes on the trigger component, next to placement. Gifts Button, Claim Reminder and the trigger host all take it:

ClaimReminder(placement: "home", alignment: .leading)

ClaimReminder(placement = "home", alignment = EncoreAlignment.LEADING)

import { EncoreClaimReminder, EncoreAlignment } from '@encorekit/react-native';

<EncoreClaimReminder placement="home" alignment={EncoreAlignment.leading} />

EncoreClaimReminder(placement: 'home', alignment: EncoreAlignment.leading)

Encore.triggers.claimReminder.mount(element, { placement: 'home', alignment: 'leading' });

<ClaimReminder placement="home" alignment="leading" />

Changing alignment only moves the trigger component. It makes no new request and keeps the look already on screen. On Android Views set the alignment property, or app:encoreAlignment in XML; on the web call setAlignment() on the handle mount() returns.

Analytics

Every trigger component reports its own impressions, taps, and dismissals to Encore’s analytics. You don’t send or handle any events.

Quickstart: add both trigger components.
Gifts Button and Claim Reminder.
Build your own button: draw the entry yourself; Encore still decides what it shows and opens the sheet.
Experiments and looks: how Encore picks and tests looks.
Troubleshooting: when a trigger component isn’t showing.

Getting Started

Guides