SmartTiming - ADict Library

📖 Przegląd

Moduł SmartTiming analizuje zachowanie użytkownika i sugeruje optymalne momenty na pokazanie reklamy, minimalizując frustrację użytkowników.

✅ Korzyści: Lepsze UX, wyższy CTR, mniej negatywnych opinii

Szybki przykład

// Konfiguracja
ADict.SmartTiming.configure(
    minSessionTimeMs = 30_000L,
    minScreenViews = 3,
    cooldownMs = 60_000L
)

// Sprawdzenie
if (ADict.SmartTiming.isGoodMoment()) {
    showInterstitial()
}

⚙️ Konfiguracja

configure(...)

Skonfiguruj parametry wykrywania.

Parametr	Typ	Domyślnie	Opis
`minSessionTimeMs`	Long	30_000	Min. czas sesji przed reklamą
`minScreenViews`	Int	3	Min. liczba ekranów
`cooldownMs`	Long	60_000	Cooldown między reklamami
`naturalBreakThresholdMs`	Long	3_000	Czas nieaktywności = przerwa
`avoidDuringInteraction`	Boolean	true	Unikaj podczas interakcji
`postInteractionDelayMs`	Long	1_500	Opóźnienie po interakcji
`minCompletedActions`	Int	0	Min. ukończonych akcji

📊 Śledzenie

trackScreenView()

Śledź wyświetlenie ekranu (automatyczne jeśli autoTrackLifecycle=true).

trackInteraction()

Śledź interakcję użytkownika (automatyczne dla touch events).

trackCompletedAction(actionName?)

Śledź ukończoną akcję (level, artykuł, etc.).

markNaturalBreak()

Oznacz naturalną przerwę (koniec video, zamknięcie dialogu).

markAdShown()

Oznacz że reklama została pokazana.

Śledzenie w grze

// Po ukończeniu poziomu
fun onLevelComplete(level: Int) {
    ADict.SmartTiming.trackCompletedAction("level_$level")
    ADict.SmartTiming.markNaturalBreak()

    // Teraz jest dobry moment!
    if (ADict.SmartTiming.isGoodMoment()) {
        showInterstitial()
    }
}

// Po obejrzeniu cutsceny
fun onCutsceneEnded() {
    ADict.SmartTiming.markNaturalBreak()
}

// Przy pokazaniu reklamy
fun showInterstitial() {
    interstitialAd.show()
    ADict.SmartTiming.markAdShown()
}

🎯 Ewaluacja

isGoodMoment(): Boolean

Sprawdź czy to dobry moment na reklamę.

evaluate(): State

Szczegółowa ewaluacja z przyczynami.

Ewaluacja stanu

val state = ADict.SmartTiming.evaluate()

println("Session: ${state.sessionDurationMs}ms")
println("Screens: ${state.screenViews}")
println("Since interaction: ${state.timeSinceLastInteraction}ms")
println("Since last ad: ${state.timeSinceLastAd}ms")
println("Natural break: ${state.isNaturalBreak}")
println("User active: ${state.isUserActive}")
println("Completed actions: ${state.completedActions}")
println("Good moment: ${state.isGoodMoment}")
println("Reasons: ${state.reasons}")

// Przykładowy output:
// Session: 45000ms
// Screens: 5
// Since interaction: 3500ms
// Since last ad: 120000ms
// Natural break: true
// User active: false
// Completed actions: 2
// Good moment: true
// Reasons: [natural_break]

🤖 Auto-show

showWhenReady(callback: () -> Unit)

Pokaż reklamę gdy będzie dobry moment.

showWhenReady(timeoutMs, callback, onTimeout?)

Z timeoutem.

cancelPending()

Anuluj oczekujące callbacki.

Auto-show z timeoutem

// Pokaż gdy będzie gotowe (bez timeoutu)
ADict.SmartTiming.showWhenReady {
    showInterstitial()
}

// Z timeoutem 30 sekund
ADict.SmartTiming.showWhenReady(
    timeoutMs = 30_000L,
    callback = { showInterstitial() },
    onTimeout = {
        Log.d("SmartTiming", "Timeout - nie znaleziono dobrego momentu")
    }
)

// Anuluj przy opuszczaniu ekranu
override fun onPause() {
    super.onPause()
    ADict.SmartTiming.cancelPending()
}

📡 Obserwacja (Flow)

Obserwacja stanu

lifecycleScope.launch {
    ADict.SmartTiming.state.collect { state ->
        if (state.isGoodMoment && shouldShowAd) {
            showInterstitial()
            shouldShowAd = false
        }
    }
}

💡 Przykłady praktyczne

Konfiguracja dla różnych typów aplikacji

// Gra casualowa - częstsze reklamy
ADict.SmartTiming.configure(
    minSessionTimeMs = 20_000L,
    minScreenViews = 2,
    cooldownMs = 45_000L,
    minCompletedActions = 1
)

// Aplikacja produktywności - rzadsze reklamy
ADict.SmartTiming.configure(
    minSessionTimeMs = 60_000L,
    minScreenViews = 5,
    cooldownMs = 180_000L,
    avoidDuringInteraction = true,
    postInteractionDelayMs = 3000L
)

// Aplikacja newsowa - balanced
ADict.SmartTiming.configure(
    minSessionTimeMs = 30_000L,
    minScreenViews = 3,
    cooldownMs = 90_000L,
    naturalBreakThresholdMs = 5000L
)

📚 data class State

sessionDurationMsLong
screenViewsInt
timeSinceLastInteractionLong
timeSinceLastAdLong
isNaturalBreakBoolean
isUserActiveBoolean
completedActionsInt
isGoodMomentBoolean
reasonsList<String>