Triggers & Targeting

Triggers

A trigger determines when the SDK checks whether to show a message. Nothing fires on its own: your app asks, and Tolinku answers with the message that should be shown at that moment, if any.

Trigger	When the message is evaluated
When your app asks	Wherever you call `showMessage()` in your own flow
Milestone	When a referral milestone is reached
Event	When your app sends a matching custom event

The first is the one most messages use, and it is deliberately in your hands. You know whether someone is signed in, mid-checkout, or halfway through onboarding; we do not. Call showMessage() at the point that suits your app and the right message appears there.

// after sign-in, so only signed-in users see it
await tolinku.showMessage();

// or narrowed to one event
await tolinku.showMessage({ trigger: 'event', triggerValue: 'purchase_completed' });

Because the messages themselves live on the server, an app that already ships a showMessage() call picks up new messages without an app update. An app with no such call cannot be sent one, so it is worth adding the call before you need it.

Audience targeting

You can target a message to a specific audience segment. When a segment is set, only users who match the segment’s rules see the message. Everyone else is silently skipped.

Examples:

Show an upgrade prompt only to free-tier users
Show a feature announcement only to users in the US
Show a re-engagement message only to users who have not opened the app in 7 days

If no audience is set, the message is shown to all users who match the trigger.

Scheduling

Set a start date and end date (UTC) to control when the message is active:

Before the start date: the message is not shown.
After the end date: the message is not shown.
Both dates are optional. Without them, the message runs indefinitely (until you deactivate it).

How often a message shows

Three separate settings control repetition, and they do different things.

What you want	Set
Show once, ever	Max impressions = 1
At most once a day	Min interval = 24 hours
Hide for a week after they dismiss it	Dismiss days = 7
Show every single time	Dismiss days = 0

Max impressions counts how many times the message has been shown, whether or not anyone dismissed it. It is the setting for a one-time announcement.

Dismiss days starts counting from an actual dismissal.

All three are enforced on the device, so the counts are per device rather than per person. Someone who reinstalls, clears data, or opens your app on a second phone starts fresh.

Priority, and how the queue advances

When several messages qualify at once, the SDK shows the one with the highest priority, and only that one. Each call shows at most one message.

The part that catches people out: priority alone never rotates. A high-priority message with no frequency cap qualifies on every check, so it shows every time and the messages below it never appear. For a queue to advance, the message at the top has to become ineligible:

Max impressions = 1 shows it once, then the next message takes over permanently.
Min interval = 24 steps it aside for a day, letting the next one through, then it returns.

Give messages distinct priorities if the order matters. Equal priorities are resolved arbitrarily.

Use cases

One-off announcement. New feature, policy change, holiday hours. Trigger when your app asks, Max impressions = 1, and an end date so it stops even for people who never open the app during the window.

Upgrade prompt for free users. Trigger when your app asks, audience set to a free-tier segment, Min interval = 168 so it appears at most weekly rather than every launch.

Post-purchase ask. Trigger event with your purchase_completed event, Max impressions = 1, so a review prompt or referral ask arrives at the moment it makes sense and never again.

Referral nudge. Trigger milestone, tied to the milestone in your referral programme, to congratulate someone or prompt the next step.

Onboarding tip sequence. Several messages, distinct priorities, each with Max impressions = 1. The highest shows first, retires itself, and the next takes over on the following launch.