Rules reference

A complete example

{
  "version": 7,
  "triggers": {
    "session_end": {
      "privateAsk": {
        "minOccurrences": 5,
        "minDaysSinceInstall": 3,
        "cooldownDays": 60,
        "skipIfSubmittedWithinDays": 180
      }
    },
    "workout_completed": {
      "storePrompt": {
        "minOccurrences": 3,
        "minDaysSinceInstall": 7,
        "cooldownDays": 120,
        "maxPerYear": 2,
        "when": {
          "appVersion": { "gte": "2.3.0" },
          "plan": { "in": ["solo", "studio"] }
        }
      }
    }
  }
}

A user who has ended five sessions, three or more days after the SDK first ran, sees the private ask — unless they sent a note in the last 180 days. A user who has completed three workouts, a week or more in, on app version 2.3.0 or later and on one of the two named plans, is offered the store prompt — at most twice in any 365 days, and never within 60 days of a note or 7 days of an ask. Here appVersion and plan are attributes the app sets itself in Attributes; conditions read only those, not the AppVersion option.

The document

A product with no rules yet serves {"version":0,"triggers":{}}: nothing asks, nothing fires.

Thresholds

Both blocks take these fields. "Occurrences" are counted on the device, one per TrackAsync call for that trigger, and never reset. "Install" is the first time the SDK ran on that device.

One field only for privateAsk:

One field only for storePrompt:

Conditions

when maps an attribute key to one condition. The attributes are the ones your app sets in Attributes. Each condition has exactly one operator:

• An attribute the app did not set fails its condition.
• eq and in compare text exactly, case included. A number or boolean attribute is compared as its invariant text; a boolean reads True or False.
• gte and lte compare either two dotted versions (two dots or more, such as 2.3.0) or two decimals (10, 0.75). A version against a decimal fails rather than guessing, so write 2.3.0, not 2.3, to compare versions. A value that is neither is refused when you save.
• Attribute keys are letters, digits, _ and -, 1 to 40 characters.

How a decision is made

Each TrackAsync call counts one occurrence, then:

1. If the loop has already shown an ask or fired a store prompt, nothing else happens for the rest of that loop's life — one action per session.
2. If the trigger has a privateAsk and all its thresholds and conditions pass, and no note was sent within skipIfSubmittedWithinDays, the ask is requested. The ask always comes first.
3. Otherwise, if the trigger has a storePrompt and all its thresholds and conditions pass, the engine then checks its fixed quiet periods and the cap, and asks the platform.

The engine's fixed limits apply whatever the rules say:

• At most 3 store prompts in any rolling 365 days, on every platform.
• No store prompt within 60 days of a note the user sent.
• No store prompt within 7 days of an ask the user was shown, whether they answered it or not.

Limits

A save is refused, with every problem listed, when the document breaks one of these:

• At most 50 triggers, each with a valid name and at least one block.
• At most 10 conditions per block, each with a valid key and exactly one operator.
• Each threshold within its allowed range (above).

The saved document must also be at most 65,536 characters long (rules.too_large). The SDK runs the same validation on a downloaded document and keeps its cached rules if the new one fails.

Reasons

When nothing happens, the Decision's Reason is one of these stable strings, safe to log: