Events, tags, attributes, and ping

These APIs require an initialized SDK and, except where noted, a current user from setUser. If no user is set, tag/attribute/ping methods return without sending a request.

Tags

• addTags(tags: List<String>) — POST to add tags for the current user.
• removeTags(tags: List<String>) — DELETE to remove tags.

Empty lists are no-ops.

Attributes

• setAttributes(attributes: Map<String, Any?>) — JSON-encoded values are wrapped for the wire format via JsonEncoding.mapToJson(...).
• addOrUpdateAttributes(attributes) — alias of setAttributes (Expo naming / iOS parity).
• removeAttributes(keys: List<String>) — DELETE selected keys.

Values must be JSON-serializable (primitives, strings, lists, nested maps). Unsupported types throw at encode time and are logged at ERROR.

ping()

Sends a heartbeat-style request for the current user (POST /users/{id}/ping). The SDK already calls ping automatically:

• Once on app foregrounding (first activity onStarted).
• Once on app backgrounding (last activity onStopped).
• Every pingIntervalSeconds while the app is in the foreground.

You can also call it explicitly if your backend uses it for presence/liveness signals.

triggerEvent(eventName, data?, callback?)

Sends POST /events for the current user.

• eventName: String — server-defined event name.
• data: Map<String, Any?>? — optional JSON-serializable payload; omitted when null.
• callback: ((Result<String>) -> Unit)? — optional. On success, called with Result.success(message) carrying the server message string. On failure (including no user), called with Result.failure(throwable).

Behavior:

• If there is no current user, the callback is invoked immediately with Result.failure(MotiSigError.UserNotSet) and no request is enqueued.
• If the SDK is not initialized (no HTTP client) when the queued work runs, the callback receives Result.failure(MotiSigError.NotInitialized).
• The callback always runs on the main thread.

MotiSig.getInstance().triggerEvent(
    eventName = "screen_view",
    data = mapOf("screen" to "home"),
) { result ->
    result.onSuccess { Log.i("MotiSig", "trigger ok: $it") }
    result.onFailure { Log.e("MotiSig", "trigger failed: $it") }
}

Java callers

All public functions are annotated with @JvmOverloads so optional parameters are exposed as Java overloads. From Java, callbacks are kotlin.jvm.functions.Function1<Result<String>, Unit> — typically easier to call from Kotlin.

Related

• User and profile
• Push notifications