PESDK/Android/Concepts

Events

Understanding how users engage with a product is critical to every business. Learn how to track how your users interact with PhotoEditor SDK for Android.

PhotoEditor SDK allows you to register an object that is being notified about events in real-time. You can then send these events to an analytics service of your choice. To receive events, you have to create a custom class that extends from EventTracker and implements Parcelable.

All possible events are declared as Strings in the static Event class in ImglySettings and ImglyState subclasses. For example, all events related to the loading or export progress are declared in the ProgressState.Event class.

For all the events that you want to track, create methods annotated with @OnEvent. Our annotation processor will generate the code to call these methods when the defined event occurs. Here's an example of how to create your event tracker:

Kotlin


class CustomEventTracker : EventTracker, Parcelable {

    private val map = hashMapOf<Class<out AbstractToolPanel>, String>()

    constructor() : super()

    constructor(parcel: Parcel) : super(parcel)

    init {
        map[MenuToolPanel::class.java] = "menu"
        map[VideoCompositionToolPanel::class.java] = "video composition"
        map[VideoCompositionTrimToolPanel::class.java] = "video composition trim"
        map[VideoLibraryToolPanel::class.java] = "video library"
        map[VideoTrimToolPanel::class.java] = "video trim"
        map[AudioOverlayOptionsToolPanel::class.java] = "audio overlay"
        map[AudioGalleryToolPanel::class.java] = "audio gallery"
        map[TransformToolPanel::class.java] = "transform"
        map[FilterToolPanel::class.java] = "filter"
        map[AdjustmentToolPanel::class.java] = "adjust"
        map[FocusToolPanel::class.java] = "focus"
        map[StickerToolPanel::class.java] = "sticker"
        map[StickerOptionToolPanel::class.java] = "sticker option"
        map[ColorOptionStickerInkToolPanel::class.java] = "sticker color ink"
        map[ColorOptionStickerTintToolPanel::class.java] = "sticker color tint"
        map[TextToolPanel::class.java] = "text"
        map[TextOptionToolPanel::class.java] = "text option"
        map[TextFontOptionToolPanel::class.java] = "text font"
        map[ColorOptionTextBackgroundToolPanel::class.java] = "text color bg"
        map[ColorOptionTextForegroundToolPanel::class.java] = "text color fg"
        map[TextDesignToolPanel::class.java] = "text design"
        map[TextDesignOptionToolPanel::class.java] = "text design option"
        map[OverlayToolPanel::class.java] = "overlay"
        map[FrameToolPanel::class.java] = "frame"
        map[BrushToolPanel::class.java] = "brush"
        map[ColorOptionBrushToolPanel::class.java] = "brush color"
    }

    /*
     * This annotated method tracks when the tool stack is changed (a tool is opened or closed)
     * ignoreReverts = true ensures that this event is not triggered again between undo/redo operations
     */
    @OnEvent(UiStateMenu.Event.TOOL_STACK_CHANGED, ignoreReverts = true)
    fun onToolStackChanged(menuState: UiStateMenu) {
        val toolName = map[menuState.currentTool.javaClass]
        // log new tool opened
    }

    /*
     * This annotated method tracks when the export starts
     */
    @OnEvent(ProgressState.Event.EXPORT_START)
    fun onExportStarted(settings: LayerListSettings) {
        // log all the added sticker ids
        settings.layerSettingsList.forEach {
            (it as? ImageStickerLayerSettings)?.stickerConfig?.id?.also {
                Log.d("Catalog", it)
            }
        }
    }

    /*
     * This annotated method tracks contrast changes after a delay of 1000ms (triggerDelay) in order to prevent too many tracking events
     * ignoreReverts = true ensures that this event is not triggered again between undo/redo operations
     */
    @OnEvent(ColorAdjustmentSettings.Event.CONTRAST, ignoreReverts = true, triggerDelay = 1000)
    fun onChangeContrast(colorAdjustmentSettings: ColorAdjustmentSettings) {
        val contrast = colorAdjustmentSettings.contrast
        // log change in contrast
    }

    /*
     * This annotated method tracks when the accept button is clicked on a tool
     * ignoreReverts = true ensures that this event is not triggered again between undo/redo operations
     */
    @OnEvent(UiStateMenu.Event.ACCEPT_AND_LEAVE, ignoreReverts = true)
    fun onAcceptTool(menuState: UiStateMenu) {
        val toolName = map[menuState.currentTool.javaClass]
        // log leave tool by accepting
    }

    /*
     * This annotated method tracks when the cancel button is clicked on a tool
     * ignoreReverts = true ensures that this event is not triggered again between undo/redo operations
     */
    @OnEvent(UiStateMenu.Event.CANCEL_AND_LEAVE, ignoreReverts = true)
    fun onCancelTool(menuState: UiStateMenu) {
        val toolName = map[menuState.currentTool.javaClass]
        // log leave tool by cancelling
    }

    companion object CREATOR : Parcelable.Creator<CustomEventTracker> {
        override fun createFromParcel(parcel: Parcel): CustomEventTracker {
            return CustomEventTracker(parcel)
        }

        override fun newArray(size: Int): Array<CustomEventTracker?> {
            return arrayOfNulls(size)
        }
    }
}

Next, register your EventTracker with the SettingsList:

Kotlin


settingsList.setEventTracker(CustomEventTracker())

Internally, the SDK also uses events for communicating between components. Refer to the custom views section of our guides to see an example of how you can create your custom view and react to the SDK's events.