Skip to content

Commit ff3ff52

Browse files
jaredlockhartclaude
andcommitted
docs: document createMessageHelper() SDK API for mobile messaging
Because * The createMessageHelper() method is the core SDK API used by the mobile messaging system but is not documented anywhere in experimenter-docs * The NimbusMessagingHelperInterface (evalJexl, stringFormat, getUuid) is also undocumented This commit * Adds an "SDK Helper API" section to the mobile messaging doc with Kotlin and Swift examples * Documents the combined NimbusMessagingHelperInterface: targeting evaluation (evalJexl), string substitution (stringFormat), and UUID generation (getUuid) * Documents lifecycle methods (destroy, clearCache) and additional context parameter Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 93fdf4c commit ff3ff52

1 file changed

Lines changed: 67 additions & 0 deletions

File tree

docs/messaging/desktop/mobile-messaging.mdx

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -536,6 +536,73 @@ Each of the following events is emitted— via Glean— at certain points while
536536

537537
Each message has a `message-key` extra.
538538

539+
## SDK Helper API
540+
541+
The Nimbus SDK provides a `createMessageHelper()` method that returns a combined helper for evaluating JEXL targeting expressions and performing string substitution. This is the core API used by the messaging system implementation.
542+
543+
<Tabs
544+
defaultValue="kotlin"
545+
values={[
546+
{ label: "Kotlin", value: "kotlin" },
547+
{ label: "Swift", value: "swift" },
548+
]
549+
}>
550+
<TabItem value="kotlin">
551+
552+
```kotlin
553+
val helper = nimbus.createMessageHelper()
554+
555+
// Evaluate a JEXL targeting expression
556+
val isEligible = helper.evalJexl("'app_opened'|eventCountNonZero('Days', 28, 0) >= 21")
557+
558+
// Format a string template with substitution
559+
val formatted = helper.stringFormat("Hello {username}, welcome to {app_name}!")
560+
561+
// Generate or retrieve a UUID for a template (stable per template string)
562+
val uuid = helper.getUuid("survey-{uuid}")
563+
564+
// Clean up native resources when done
565+
helper.destroy()
566+
```
567+
568+
</TabItem>
569+
<TabItem value="swift">
570+
571+
```swift
572+
let helper = nimbus.createMessageHelper()
573+
574+
// Evaluate a JEXL targeting expression
575+
let isEligible = helper.evalJexl(expression: "'app_opened'|eventCountNonZero('Days', 28, 0) >= 21")
576+
577+
// Format a string template with substitution
578+
let formatted = helper.stringFormat(template: "Hello {username}, welcome to {app_name}!")
579+
580+
// Generate or retrieve a UUID for a template (stable per template string)
581+
let uuid = helper.getUuid(template: "survey-{uuid}")
582+
583+
// Clean up native resources when done
584+
helper.destroy()
585+
```
586+
587+
</TabItem>
588+
</Tabs>
589+
590+
The helper implements `NimbusMessagingHelperInterface`, which combines:
591+
- **`NimbusTargetingHelperInterface`**`evalJexl(expression)` for targeting evaluation
592+
- **`NimbusStringHelperInterface`**`stringFormat(template)` and `getUuid(template)` for string substitution
593+
594+
You can optionally pass additional context attributes when creating the helper:
595+
596+
```kotlin
597+
val helper = nimbus.createMessageHelper(additionalContext = JSONObject().apply {
598+
put("current_tab_url", currentUrl)
599+
})
600+
```
601+
602+
:::note
603+
Call `destroy()` when done with the helper to free the backing Rust native object. Call `clearCache()` to reset the JEXL evaluation cache if the targeting context has changed.
604+
:::
605+
539606
## Extending the System
540607

541608
Much of the system relies on Nimbus [merging together JSON objects](/technical-reference/fml/growable-collections). We have seen this in the `messages` object which can contain messages from the default configuration, rollouts, and experiments.

0 commit comments

Comments
 (0)