Skip to main content

Notifications

Jest allows developers to schedule notification messages to re-engage players and drive retention. Using the Jest SDK, you can customize a notification's text, call to action (CTA), and image.

The Jest platform handles messaging infrastructure and delivery, subsidizing 100% of messaging costs and abstracting away operational complexity. This includes managing regulated messaging requirements such as consent collection, required disclosures, and robust opt-out mechanisms.

For guidance on designing effective notification strategies, copywriting, and scheduling patterns, see Notifications best practices.

Notification channels​

There are two notification delivery channels on Jest: the platform Home tab and SMS / RCS text messages.

Home tab​

When your game is Approved and set to Public, all scheduled notifications appear in the Jest platform Home tab.

SMS / RCS messages​

Jest may also deliver notifications via SMS or RCS. Channel selection is based on availability and the user's messaging settings.

Home notification
Home notification
SMS notification
SMS notification
RCS notification
RCS notification

Notification mechanics​

Jest games use the Jest SDK notification methods to schedule notifications. At the scheduled time, notifications are shown in the Home tab on Jest.com.

Once per day, Jest selects at most one scheduled notification per user across all games on the platform to deliver to the user's messaging inbox. The platform selects the notification most likely to convert, taking into account the priority provided by the SDK. Delivery time is determined per user based on the scheduled time defined by the game and observed engagement patterns, while respecting compliance requirements. Messages are delivered via SMS or RCS, depending on availability and user preferences.

Notifications API​

Here is some example code to demonstrate scheduling notifications on the Jest gaming platform.

note

The Jest platform will only send notifications to registered users. You can check a user's status with player.is_registered and prompt players to log in via the SDK.

notifications.schedule(options)​

To schedule a notification, create a JestNotificationOptions resource and pass it to the schedule method.

Notifications can be scheduled from today (D0) up to 7 days ahead. scheduled_in_days must be between 0 and 7 days (inclusive), and date must be within the next 7 days. A scheduled_in_days of 0 lands 10 minutes from now, so a same-day notification is far enough ahead to be delivered.

Notifications can be scheduled in one of two ways:

  • Exact scheduling using date, which ensures the notification becomes eligible for delivery after the specified date and time. Note that delivery is not guaranteed at the exact scheduled moment, as messaging must comply with mandated quiet hours and other delivery constraints.
  • Fuzzy scheduling using scheduled_in_days, which schedules a notification 0 to 7 days from now and allows the platform to determine an appropriate delivery time for each user.

Exact scheduling is suited for fixed events or deadlines where timing matters. Fuzzy scheduling is intended for notifications that are relevant within a given day, allowing the platform to determine an appropriate delivery time for each user.

var notifications = JestSDK.notifications

# Schedule for specific date/time (exact scheduling)
var options = JestNotificationOptions.new()
options.body = "Your energy is full!"
options.cta_text = "Play Now"
options.priority = "high"
options.identifier = "energy_full"
options.date = "2024-01-15T10:00:00Z"
notifications.schedule(options)

# Schedule using fuzzy timing (0-7 days from now)
var options2 = JestNotificationOptions.new()
options2.body = "We miss you! Come back for a special reward."
options2.cta_text = "Claim Reward"
options2.priority = "medium"
options2.identifier = "comeback_day3"
options2.scheduled_in_days = 3
notifications.schedule(options2)

Options properties​

PropertyTypeRequiredDescription
bodyStringYesThe main text of the notification. Must be 1-2000 characters.
cta_textStringYesCall-to-action button text. Must be 1-50 characters.
identifierStringYesUnique identifier for rescheduling or unscheduling.
dateString*ISO 8601 date/time to schedule. Must be within 7 days. Mutually exclusive with scheduled_in_days.
scheduled_in_daysint*Days from now to schedule (0-7); 0 is later today. Mutually exclusive with date.
titleStringNoOptional title shown above the body. Up to 200 characters.
priorityStringNoPriority level: "low", "medium", "high", or "critical". Default is "medium".
asset_referenceStringNoReference to a pre-approved asset (image or video).
assetStringNoInline image as a base64 data URL (PNG, JPEG, or WebP, at most 2MB). Mutually exclusive with asset_reference.
entry_payloadDictionaryNoCustom data payload attached to the notification.

* Either date or scheduled_in_days must be provided, but not both.

Priority levels​

The priority property accepts one of four string values:

  • "low" — Low priority notification
  • "medium" — Medium priority notification (default)
  • "high" — High priority notification
  • "critical" — Critical priority notification

Attaching assets​

To attach an asset (image or video) to your notification, first upload and submit it for approval in the Manage images section of the Developer Console. Only approved assets can be referenced in notifications.

var options = JestNotificationOptions.new()
options.body = "Your daily reward is ready!"
options.cta_text = "Collect"
options.priority = "medium"
options.identifier = "daily_reward"
options.scheduled_in_days = 1
options.asset_reference = "daily_reward_banner"
JestSDK.notifications.schedule(options)

If an asset_reference is invalid, unapproved, or archived, the notification will use your game's Hero image as a fallback and log an error in the Events page. If asset_reference is not set, it will also fall back to the Hero image.

Attaching an inline asset​

If the image is generated at runtime, for example a scoreboard or a personalized card, pass it as a base64 data URL in asset instead of uploading it first. PNG, JPEG, and WebP are accepted, up to 2MB, and the image must be large enough to crop to 3:2. asset and asset_reference cannot be combined.

Jest stores the image as a notification asset for your game, so it appears in Manage images with a reference starting with inline-, and it is moderated before the notification is delivered. If the image is rejected by moderation, the notification is still delivered with your game's Hero image and an error is logged in the Events page.

var png := image.save_png_to_buffer()

var options = JestNotificationOptions.new()
options.body = "You reached the top 10 today!"
options.cta_text = "See the board"
options.priority = "medium"
options.identifier = "daily_rank"
options.scheduled_in_days = 1
options.asset = "data:image/png;base64," + Marshalls.raw_to_base64(png)
JestSDK.notifications.schedule(options)

Attaching entry payload​

You can attach custom data to notifications that will be passed to the game when the player opens the notification:

var options = JestNotificationOptions.new()
options.body = "Your farm needs attention!"
options.cta_text = "Visit Farm"
options.priority = "high"
options.identifier = "farm_reminder"
options.scheduled_in_days = 1
options.entry_payload = {
    "notification_type": "farm_reminder",
    "day": 1
}
JestSDK.notifications.schedule(options)

notifications.unschedule(identifier)​

To unschedule an already scheduled notification, use this method with the notification's unique identifier.

var notifications = JestSDK.notifications

notifications.unschedule("energy_full")

If you schedule a notification with an existing identifier, the original notification will be unscheduled and replaced with the new one. You don't need to unschedule the original notification first.

Moderation and delivery constraints​

Notifications are subject to platform review and moderation. Content that violates the Acceptable Use Policy may be blocked from delivery. For more details, see Review and moderation.