Screen-View Tracking (Activities & Fragments)

Automatically track screen views whenever the visible Activity or Fragment changes.

Overview

Sees360 can automatically emit a system analytics event whenever the visible Activity or Fragment changes.

• Event name: sees_screen_view (predefined/system)
• Primary param: screen_name — a stable screen name you define (see below)

The API lowercases all payload keys and values before persisting/exporting. Emit lowercase for consistency (home, settings).

Requirements

• androidx.appcompat:appcompat
• androidx.fragment:fragment-ktx
• SDK initialized: Sees360.initialize(context, apiKey, identifier)
• (Optional) Usage Stats permission if you also use usage-stats features. Screen-view events do not require it.

Tracking starts automatically when you initialize the SDK — no further wiring needed.

How it works

The SDK registers:

• Application.ActivityLifecycleCallbacks → sends on Activity resume.
• FragmentManager.FragmentLifecycleCallbacks → sends on Fragment resume (and actually visible).

For each screen, we determine a screen_name using this order:

Activity

1. If the Activity implements ScreenNameProvider, use screenName().
2. Else, use the Activity label from the manifest (if not blank).
3. Else, use the class simple name.

Fragment

1. If the Fragment implements ScreenNameProvider, use screenName().
2. Else, if arguments["route"] is set, use that.
3. Else, if the Fragment tag is set, use that.
4. Else, use the class simple name.

Quick start

1. Initialize the SDK

Sees360.initialize(applicationContext, apiKey = BuildConfig.API_KEY, identifier = myIdentifier)

2. (Recommended) Provide explicit names

Activities

import com.sees360.sdk.main.tracking.ScreenNameProvider

class HomeActivity : AppCompatActivity(), ScreenNameProvider {
    override fun screenName() = "home"
}

If you prefer the manifest label fallback:

<activity
    android:name=".ui.SettingsActivity"
    android:label="settings" />

Labels may be localized. For stable analytics keys across locales, prefer ScreenNameProvider.

Fragments

class DetailsFragment : Fragment(R.layout.fragment_details), ScreenNameProvider {
    override fun screenName() = "details"
}

If you don’t want to implement the interface, you can set a stable key via arguments or tag:

// arguments-based (will be picked up as screen_name)
val frag = DetailsFragment().apply {
    arguments = bundleOf("route" to "details")
}
supportFragmentManager.beginTransaction()
    .replace(R.id.container, frag)
    .commit()

// or tag-based
supportFragmentManager.beginTransaction()
    .replace(R.id.container, DetailsFragment(), /* tag = */ "details")
    .commit()

Best practices

• Stable keys only. No IDs or ephemeral UI state (profile, not profile:42).
• Lowercase everything. The backend lowercases anyway — emit lowercase for consistent logs.
• Prefer ScreenNameProvider. It’s explicit and avoids localization/obfuscation surprises.
• One visible Fragment at a time. We emit when a Fragment is resumed & shown. With ViewPager2 or nested fragments, we send when a page/child becomes the active, visible one.
• PII-free. Never include user data in screen_name.

Troubleshooting

• No events firing: Make sure the SDK is initialized in the process before your screens are shown.
• Unexpected names: Implement ScreenNameProvider to override labels/class names.
• Multiple fragments on screen: The SDK sends for the Fragment that is resumed and visible. If you show overlays (e.g., DialogFragment) and don’t want them counted, avoid giving them a special name; keep the key stable (e.g., still details) or move dialog logic so it isn’t considered a new “screen” for analytics.
• Duplicate events: Typically indicates multiple resumes in quick succession; this is deduped per source internally, but ensure you aren’t rapidly attaching/detaching the same Fragment.

Event reference

• Name: sees_screen_view
• Payload (lowercased by backend):
  • screen_name: String — canonical screen key (lowercase)

{
  "event_name": "sees_screen_view",
  "payload": { "screen_name": "settings" }
}

Privacy & security

• Keep keys generic and stable (e.g., settings, checkout, search_results).
• If you support analytics opt-out, gate SDK initialization or add a setting in your app to disable analytics features (future SDK versions may expose toggles).

Do not include PII in screen_name.