SmartTiming - ADict Library

📖 PrzeglądOverview

Moduł SmartTiming analizuje zachowanie użytkownika i sugeruje optymalne momenty na pokazanie reklamy, minimalizując frustrację użytkowników.The SmartTiming module analyzes user behavior and suggests optimal moments for showing ads, minimizing user frustration.

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

Szybki przykładQuick Example

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

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

⚙️ KonfiguracjaConfiguration

configure(...)

SkonfigurujConfigure parametry wykrywania.

ParametrParameter	TypType	DomyślnieDefault	OpisDescription
`minSessionTimeMs`	Long	30_000	Min. czas sesji przed reklamąMin. session time before ad
`minScreenViews`	Int	3	Min. liczba ekranówMin. screen count
`cooldownMs`	Long	60_000	Cooldown między reklamamiCooldown between ads
`naturalBreakThresholdMs`	Long	3_000	Czas nieaktywności = przerwaInactivity time = break
`avoidDuringInteraction`	Boolean	true	Unikaj podczas interakcji
`postInteractionDelayMs`	Long	1_500	Opóźnienie po interakcjiDelay after interaction
`minCompletedActions`	Int	0	Min. ukończonych akcjiMin. completed actions

📊 Śledzenie📊 Tracking

trackScreenView()

Śledź wyświetlenie ekranu (automatyczne jeśli autoTrackLifecycle=true).Track screen view (automatic if autoTrackLifecycle=true).

trackInteraction()

Śledź interakcję użytkownika (automatyczne dla touch events).Track user interaction (automatic for touch events).

trackCompletedAction(actionName?)

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

markNaturalBreak()

Oznacz naturalną przerwę (koniec video, zamknięcie dialogu).Mark natural break (end of video, dialog close).

markAdShown()

Oznacz że reklama została pokazana.Mark that an ad has been shown.

Śledzenie w grzeTracking in game

// 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ę.Check if it's a good moment for an ad.

evaluate(): State

Szczegółowa ewaluacja z przyczynami.Detailed evaluation with reasons.

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.Show an ad when it's a good moment.

showWhenReady(timeoutMs, callback, onTimeout?)

Z timeoutem.

cancelPending()

Anuluj oczekujące callbacki.Cancel pending callbacks.

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ładyExamples praktyczne

KonfiguracjaConfiguration 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>