emitExtensionUsedEvent#

Fully qualified name: omni::ext::emitExtensionUsedEvent

Defined in omni/ext/ExtensionsUtils.h

inline void omni::ext::emitExtensionUsedEvent(
carb::cpp::string_view extensionId,
carb::cpp::string_view windowOrActionName,
carb::cpp::string_view context = "",
)#

Helper function to emit a telemetry event indicating that an extension was used.

  • the resultant data will be inaccurate and misleading - it will no longer be an accurate view of the relative usage frequency of different extensions, windows, or actions.

  • the bandwidth usage related to transmitting this event will increase. This will become bounded only by user activity which will not be deterministic per session.

  • the storage cost for this event will increase significantly and will only be bounded by user activity.

Remark

This reports that an extension, window, or action was used. This is intended to be emitted at most once for each combination of extension ID and window or action name per session. This is intended to be emitted at key moments of user interaction with an extension, such as executing a command or using a tool provided by the extension. Calling this more than once per extension/window or extension/action combination will have multiple downsides:

Because of these potential problems, ensuring that calls to this helper function are unique in a session is enforced internally for all combinations of extension ID and window or action name. A caller may still make multiple calls to this helper, but they should do so with the knowledge that repeated calls with the same first two parameters will be silently ignored.

Parameters:

  • extensionId – [in] The name of the extension that was used. This could be the extension that owns a window or UI element that was interacted with, or the extension that registered an action that was used. This may not be an empty string. This must include the extension’s internal name and its version number to ensure the data is useful. For example, omni.kit.telemetry-0.1.0.

  • windowOrActionName – [in] The name of the window that was interacted with or the action ID of a registered hotkey that was used. This should be a user friendly display name. This may not be an empty string. For example, Viewport or Content Browser for windows, or omni.kit.action.myAction for actions.

  • context – [in] A caller specified string describing the specific action or feature of the extension that was used. This is only required to provide extra context for why or how the extension, window, or action was used. This may be an empty string if not needed.

Returns:

No return value.