Events - Alke Analytics Documentation

Track pageviews and custom events to understand user behavior across your application.

Pageview Tracking

Pageviews are the fundamental tracking unit. They capture when a user views a page or screen.

Automatic Pageviews

With autoPushPageview: true (default), a pageview is tracked automatically on initialization.

Manual Pageviews

For single-page applications or custom navigation:

// Track a pageview manually
alkeAnalytics.pushPageView();

The SDK automatically captures:

Current URL (normalized, without tracking parameters)
Page title
Referrer
Session data

Navigating in a single-page application

pushPageView() opens a page; it does not close the previous one. Declare the navigation itself so the SDK knows where one page ends and the next begins:

alkeAnalytics.pushNavigation();   // reports and closes the current page
alkeAnalytics.pushPageView();     // opens the next one

pushNavigation() reports the page being left, clears its context — content dimensions, goal, custom data — restarts the active time, engagement, scroll depth and video sequence from zero, then re-derives the automatic dimensions from the page now displayed. Call it after your router has changed the url and rendered, or it reads the previous page. Reader and session data (loggedIn, subscriptionStatus, abtest, traffic source, …) follow the visit and are kept.

What the page being left had measured is frozen at that instant, not just reset: a report of that page still in flight is finalised later with its own engagement, active time and Web Vitals. The boundary also opens the next pageviewId, so an ad request or an event that follows it already belongs to the next page.

See Content Dimensions for which side of the boundary each value falls on.

Breaking change

pushPageView() used to reset the per-page counters — active time, engagement, scroll depth, video sequence — and to open a new pageviewId. It no longer does either: pushNavigation() is the page boundary, and the only one. This also affects sites that are not single-page applications but call pushPageView() several times on the same document — infinite scroll, multi-step funnels: the second pageview now inherits the scroll depth and video sequence of the first, and reports the same pageviewId, because without a navigation both describe the same page.

pushNavigation() between two pushPageView() calls on the same document is therefore required, not merely recommended. Omitting it is not just a matter of counters: two pageviews of the same url within the same minute become indistinguishable in storage, so the second one never appears in your reports, and the ad revenue it earned is attributed to the first.

pushPageView()

// Basic pageview
AlkeAnalytics.pushPageView(
    url: "myapp://home",
    title: "Home Screen"
)

// With custom data
AlkeAnalytics.pushPageView(
    url: "myapp://article/123",
    title: "Article Title",
    customData: [
        1: "category_tech",
        2: "author_john"
    ]
)

When to call

Call pushPageView() in onAppear (SwiftUI) or viewDidAppear (UIKit).

Navigating between screens

pushPageView() opens a screen’s report; it does not close the previous one. Declare the navigation itself, exactly as on the web:

AlkeAnalytics.pushNavigation()   // reports and closes the current screen
AlkeAnalytics.pushPageView(url: "myapp://sport", title: "Sport")

pushNavigation() reports the screen being left, clears its context — content dimensions, goal, custom data — and restarts active time and engagement from zero. Reader and session data (loggedIn, subscriptionStatus, abtest, …) follow the visit and are kept. There is no automatic extraction to re-derive on a native platform, so — unlike the web — you never have to call it “after the router has rendered”: call it when the screen changes.

The boundary also opens the next pageviewId, so an event sent after it already belongs to the screen that follows.

See Content Dimensions for which side of the boundary each value falls on.

Breaking change

pushPageView() used to open a new pageviewId and reset the per-screen counters. It no longer does either: pushNavigation() is the screen boundary, and the only one.

An existing integration that pushes one pageview per screen and never calls pushNavigation() now shares a single pageviewId for the whole session, and every screen inherits the custom data and content dimensions of the previous one. Worse, two pageviews of the same url within the same minute become indistinguishable in storage, so the second one never appears in your reports.

Adding pushNavigation() between screens is therefore required, not merely recommended.

pushPageView()

// Basic pageview
AlkeAnalytics.pushPageView(
    url = "myapp://home",
    title = "Home Screen"
)

// With custom data
AlkeAnalytics.pushPageView(
    url = "myapp://article/123",
    title = "Article Title",
    customData = mapOf(
        1 to "category_tech",
        2 to "author_john"
    )
)

When to call

Call pushPageView() in onResume() of your Activity or Fragment.

Navigating between screens

pushPageView() opens a screen’s report; it does not close the previous one. Declare the navigation itself, exactly as on the web:

AlkeAnalytics.pushNavigation()   // reports and closes the current screen
AlkeAnalytics.pushPageView(url = "myapp://sport", title = "Sport")

In Compose, the boundary belongs where the screen is entered, not where it is composed — a recomposition must not report a navigation:

LaunchedEffect(article.id) {
    AlkeAnalytics.pushNavigation()
    AlkeAnalytics.pushPageView(url = article.deeplink, title = article.title)
}

The boundary also opens the next pageviewId, so an event sent after it already belongs to the screen that follows.

See Content Dimensions for which side of the boundary each value falls on.

Breaking change

pushPageView() used to open a new pageviewId and reset the per-screen counters. It no longer does either: pushNavigation() is the screen boundary, and the only one.

Adding pushNavigation() between screens is therefore required, not merely recommended.

trackPageview()

AlkeAnalytics.trackPageview({
  url: 'myapp://home',
  title: 'Home'
});

AlkeAnalytics.trackPageview({
  url: `myapp://video/${video.id}`,
  title: video.title,
  customData: { cd1: 'documentary' }
});

Navigating between screens

trackPageview() opens a screen’s report; it does not close the previous one. Declare the navigation itself:

AlkeAnalytics.pushNavigation();   // reports and closes the current screen
AlkeAnalytics.trackPageview({ url: 'myapp://sport', title: 'Sport' });

pushNavigation() reports the screen being left, clears its context — content dimensions, goal, custom data — and restarts engagement from zero. Reader and session data (loggedIn, subscriptionStatus, abtest, …) follow the visit and are kept.

The boundary also opens the next pageviewId, so an event sent after it already belongs to the screen that follows.

Breaking change

trackPageview() used to open a new pageviewId and reset the per-screen counters. It no longer does either: pushNavigation() is the screen boundary, and the only one — the same contract as the web and the other native SDKs.

An existing Tizen integration that pushes one pageview per screen and never calls pushNavigation() now shares a single pageviewId for the whole session, and every screen inherits the custom data and content dimensions of the previous one. Two pageviews of the same url within the same minute also become indistinguishable in storage, so the second one never appears in your reports.

Adding pushNavigation() between screens is therefore required, not merely recommended.

Custom Events

Track specific user interactions beyond pageviews.

pushEvent()

// Simple event
alkeAnalytics.pushEvent('button_click', 'share_button');

// Event with custom data included
alkeAnalytics.pushEvent('purchase', 99.99, true);

Parameter	Type	Description
`eventName`	stringrequired	Name of the event (e.g., 'button_click', 'video_play')
`eventValue`	string\|number\|booleanoptional	Optional value associated with the event
`includeCustomData`	booleanoptional	Include current custom data with this event. Default: `false`

Named dimensions ride every event

includeCustomData gates the custom data slots cd1 to cd10 only. The named dimensions — content hierarchy, article metadata, reader context — are attached to every event of the page, custom events included, whatever that flag is set to. They are resolved when the event is actually sent, so a value set just after pushEvent() still reaches it. See Content Dimensions.

pushEvent()

// Simple event
AlkeAnalytics.pushEvent(name: "button_click")

// Event with value
AlkeAnalytics.pushEvent(
    name: "video_progress",
    value: 50  // 50% watched
)

// Event with custom data
AlkeAnalytics.pushEvent(
    name: "purchase",
    value: 99.99,
    customData: [
        1: "product_abc",
        2: "electronics"
    ]
)

pushEvent()

// Simple event
AlkeAnalytics.pushEvent(name = "button_click")

// Event with value
AlkeAnalytics.pushEvent(
    name = "video_progress",
    value = 50  // 50% watched
)

// Event with custom data
AlkeAnalytics.pushEvent(
    name = "purchase",
    value = 99.99,
    customData = mapOf(
        1 to "product_abc",
        2 to "electronics"
    )
)

Flushing Events

Events are automatically sent when:

The page/app goes to background
The page is about to unload (web)
A new pageview is tracked

You can also manually flush:

Events are flushed automatically on visibilitychange and pagehide. Manual flush is rarely needed.

Engagement Tracking

Track how much of the content users actually consume.

Scroll engagement is tracked automatically. The SDK records the maximum scroll depth as a percentage (0-100).

// Override with custom engagement (e.g., video progress)
alkeAnalytics.setEngagementPercent(75);