Skip to main content
The moment is the reason your app shows offers at this point: a kept streak, a level reached, a saved photo. It is the one thing only your app knows. Add it to each placement call. Encore records it with every show and uses it to learn which premium brand offers (a real perk a brand funds to acquire customers) fit each moment.
Requires iOS, Android, or Web SDK 2.7.0, or the React Native or Flutter release that requires native SDK 2.7.0. Older SDKs keep working: a placement call with no moment is still valid. In debug builds with the log level set to debug, these SDKs log one warning for each placement shown with no moment.

Add the moment

Add .moment(...) to the placement call. This is the whole integration for most apps:
Contracts: moment() on placement() for iOS, Android, Web, React Native, and Flutter.

When the SDK asks for offers

When your app starts, the SDK asks Encore for offers once. For up to 5 minutes, or the time Encore’s settings (/config) set, a show() at any placement uses that list. After that, the next show() asks for a new list. The moment you pass is sent with every request made for a placement and recorded with every show, whichever list the show uses. Encore can later turn on earliest-point serving for your app from its own settings, with no code change. With it on, a trigger component asks for offers when it appears, and a placement reuses a list only for the same placement and the same moment, for up to 5 minutes or the time Encore’s settings (/config) set. A changed moment then asks for a new list at once.

Choose the moment type

Every SDK has the same moment types, in three kinds. Pick the one that names why the user is here now. Progress milestones carry a number from your app:
  • Streak: consecutive active periods, such as 7 days in a row. A break in use resets it.
  • Milestone: progress the user reached, such as level 10. It stays when the user is away.
  • Lapse: days since the user was last active.
  • Paywall abandon: how many times the user left your paywall this session.
  • Purchase: the amount the user just paid. On iOS and Android, the SDK uses the device locale’s currency; pass a currency only when the amount is in another one, and your value wins. On Web, pass the currency with every purchase: the SDK uses the browser language’s currency only when that language names a region, such as es-MX, and sends no currency for a bare language such as es.
Action is something the user just did. Its label is the action’s name, such as photo_saved. If your app counts this action per user, pass the count, such as 12 for the twelfth saved photo. Encore uses it to tell a new achievement from a repeat of the same one. With earliest-point serving on, a new count is a new moment, so the next show asks for a fresh list at once. Without a count, a repeat of the same action reuses the list for up to 5 minutes. Custom is a moment none of the other types describes. Its label names it, with an optional number. When you have no number for an action or a custom moment, leave it out. Do not pass 0 in its place: Encore reads 0 as a real value. Labels are 32 characters or fewer. Encore stores labels in snake case, so photoSaved and photo_saved are the same label. Use one label for one action or moment across your app.

Describe your placement in code (optional)

After the moment, you can describe the placement: where it sits in your app (its location) and what opens it (its trigger). These values belong to your app. They change when you ship a new screen or button, so set them in the same code, on the placement call. They are optional: without them the placement still serves, and Encore has less to rank offers with for that spot. Trigger components, such as the gifts button, report their own trigger values, so you add nothing for them. They take the moment the same way the placement call does: see Add the moment to a trigger component. For a placement your own UI opens, lead with the moment, then add .location() and .trigger(). Use embedded when your launcher sits inside a screen, popup or sheet that shows other content (a button in a celebration popup), and standalone when the launcher is the whole UI that appears (a toast, a drop-down notice, a floating badge).
Contracts: location() and trigger() on placement() for iOS, Android, Web, React Native, and Flutter. Set these on the placement call, never in configure(): one app has many placements, each with its own values. When one placement ID shows in more than one place, pass the values for the place it shows in on each call.

Respect your app’s personalization switch

Skip this section if your app has no personalization setting of its own. If it has one, pass the user’s choice to Encore. With personalization off, Encore uses only the request, never what it knows about that user, and stores no user profile data from those requests. The request still carries device facts, such as the device model and OS version, because they describe the device, not the user. Offers still show for that user.
Contracts: personalization on configure() for iOS, Android, Web, React Native, and Flutter. The device saves the value, so it holds after the app restarts and when another user signs in. Pass true when the user turns personalization back on. Contracts: setPersonalization for iOS, Android, Web, React Native, and Flutter.

What the SDK reads on its own

The SDK fills the rest of each request by itself, from the device and the privacy signals already on it. The full list, and the App Store and Google Play privacy answers it needs, is on Store Privacy Disclosures. A Web app cannot read its own version, so it passes the optional appVersion to configure().