From ff3ff5283ea7e6f67b3c7bf0ca41737d8c3930f5 Mon Sep 17 00:00:00 2001
From: Jared Lockhart <119884+jaredlockhart@users.noreply.github.com>
Date: Wed, 25 Feb 2026 11:37:39 -0500
Subject: [PATCH] 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>
---
 docs/messaging/desktop/mobile-messaging.mdx | 67 +++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/docs/messaging/desktop/mobile-messaging.mdx b/docs/messaging/desktop/mobile-messaging.mdx
index b7b78d69e..07278a6a8 100644
--- a/docs/messaging/desktop/mobile-messaging.mdx
+++ b/docs/messaging/desktop/mobile-messaging.mdx
@@ -536,6 +536,73 @@ Each of the following events is emitted— via Glean— at certain points while
 
 Each message has a `message-key` extra.
 
+## SDK Helper API
+
+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.
+
+<Tabs
+  defaultValue="kotlin"
+  values={[
+    { label: "Kotlin", value: "kotlin" },
+    { label: "Swift", value: "swift" },
+  ]
+}>
+<TabItem value="kotlin">
+
+```kotlin
+val helper = nimbus.createMessageHelper()
+
+// Evaluate a JEXL targeting expression
+val isEligible = helper.evalJexl("'app_opened'|eventCountNonZero('Days', 28, 0) >= 21")
+
+// Format a string template with substitution
+val formatted = helper.stringFormat("Hello {username}, welcome to {app_name}!")
+
+// Generate or retrieve a UUID for a template (stable per template string)
+val uuid = helper.getUuid("survey-{uuid}")
+
+// Clean up native resources when done
+helper.destroy()
+```
+
+</TabItem>
+<TabItem value="swift">
+
+```swift
+let helper = nimbus.createMessageHelper()
+
+// Evaluate a JEXL targeting expression
+let isEligible = helper.evalJexl(expression: "'app_opened'|eventCountNonZero('Days', 28, 0) >= 21")
+
+// Format a string template with substitution
+let formatted = helper.stringFormat(template: "Hello {username}, welcome to {app_name}!")
+
+// Generate or retrieve a UUID for a template (stable per template string)
+let uuid = helper.getUuid(template: "survey-{uuid}")
+
+// Clean up native resources when done
+helper.destroy()
+```
+
+</TabItem>
+</Tabs>
+
+The helper implements `NimbusMessagingHelperInterface`, which combines:
+- **`NimbusTargetingHelperInterface`** — `evalJexl(expression)` for targeting evaluation
+- **`NimbusStringHelperInterface`** — `stringFormat(template)` and `getUuid(template)` for string substitution
+
+You can optionally pass additional context attributes when creating the helper:
+
+```kotlin
+val helper = nimbus.createMessageHelper(additionalContext = JSONObject().apply {
+    put("current_tab_url", currentUrl)
+})
+```
+
+:::note
+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.
+:::
+
 ## Extending the System
 
 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.