📖 Przegląd

Moduł Analytics to agregator analityki umożliwiający wysyłanie zdarzeń do wielu providerów jednocześnie. Jeden log → wszystkie providery.

💡 Automatyczna inicjalizacja: W trybie debug automatycznie dodawany jest ConsoleProvider, który loguje wszystkie eventy do konsoli.
Szybki przykład
// Dodaj providera Firebase
ADict.Analytics.addProvider(Analytics.FirebaseProvider(context))

// Jeden log → wszystkie providery
ADict.Analytics.log("purchase", mapOf(
    "product_id" to "premium",
    "price" to 9.99
))

🔌 Providery

Wbudowane providery

FirebaseProvider

Provider dla Firebase Analytics.

ADict.Analytics.addProvider(Analytics.FirebaseProvider(context))

ConsoleProvider

Provider debugowy logujący do konsoli (automatycznie dodawany w debug).

ADict.Analytics.addProvider(Analytics.ConsoleProvider())

addProvider(provider: AnalyticsProvider)

Dodaj provider analityki.

Parametry:

  • provider: AnalyticsProvider - Implementacja interfejsu AnalyticsProvider

removeProvider(name: String)

Usuń provider po nazwie.

setEnabled(enabled: Boolean)

Włącz/wyłącz całą analitykę.

getProviders(): List<String>

Pobierz listę aktywnych providerów.

📝 Logowanie zdarzeń

log(event: String, params: Map<String, Any?>)

Zaloguj zdarzenie z parametrami.

Parametry:

  • event: String - Nazwa zdarzenia
  • params: Map<String, Any?> - Mapa parametrów

log(event: String, vararg params: Pair<String, Any?>)

Zaloguj zdarzenie z parami klucz-wartość.

screenView(screenName: String, screenClass: String?)

Zaloguj wyświetlenie ekranu.

Logowanie zdarzeń
// Z mapą
ADict.Analytics.log("button_click", mapOf(
    "button_name" to "buy_now",
    "screen" to "product_detail",
    "product_id" to "123"
))

// Z vararg
ADict.Analytics.log("button_click",
    "button_name" to "buy_now",
    "screen" to "product_detail"
)

// Screen view
ADict.Analytics.screenView("ProductScreen", "ProductActivity")

// Prosty event bez parametrów
ADict.Analytics.log("app_opened")

👤 Użytkownik

setUserId(id: String?)

Ustaw ID użytkownika dla wszystkich providerów.

setUserProperty(name: String, value: Any?)

Ustaw właściwość użytkownika.

setUserProperties(properties: Map<String, Any?>)

Ustaw wiele właściwości jednocześnie.

Właściwości użytkownika
// Ustaw ID
ADict.Analytics.setUserId("user_12345")

// Ustaw pojedynczą właściwość
ADict.Analytics.setUserProperty("plan_type", "premium")
ADict.Analytics.setUserProperty("country", "PL")

// Ustaw wiele właściwości
ADict.Analytics.setUserProperties(mapOf(
    "plan_type" to "premium",
    "signup_date" to "2024-01-15",
    "referral_source" to "google"
))

// Wyczyść
ADict.Analytics.setUserId(null)
ADict.Analytics.setUserProperty("plan_type", null)

📦 Predefiniowane eventy

Analytics oferuje gotowe metody dla często używanych zdarzeń:

logPurchase(productId, price, currency, extras)

Zakup produktu.

ADict.Analytics.logPurchase(
    productId = "premium_monthly",
    price = 9.99,
    currency = "USD",
    extras = mapOf("promo_code" to "SALE20")
)

logSubscriptionStart(productId, price, currency, period)

Rozpoczęcie subskrypcji.

ADict.Analytics.logSubscriptionStart(
    productId = "premium_yearly",
    price = 79.99,
    currency = "USD",
    period = "yearly"
)

logAdImpression(adType, adUnit, provider, zone)

Wyświetlenie reklamy.

ADict.Analytics.logAdImpression(
    adType = "interstitial",
    adUnit = "ca-app-pub-xxx",
    provider = "admob",
    zone = "level_complete"
)

logAdClick(adType, adUnit, provider)

Kliknięcie w reklamę.

logError(errorType, message, extras)

Błąd w aplikacji.

ADict.Analytics.logError(
    errorType = "api_error",
    message = "Failed to load data",
    extras = mapOf("endpoint" to "/api/products")
)

logShare(contentType, contentId, method)

Udostępnienie treści.

logSearch(query, resultsCount)

Wyszukiwanie.

logTutorialComplete(tutorialId)

Ukończenie tutoriala.

logLevelComplete(level, score)

Ukończenie poziomu w grze.

🔧 Własny provider

Możesz stworzyć własny provider implementując interfejs AnalyticsProvider:

interface AnalyticsProvider

  • name String Unikalna nazwa providera
  • log(event, params) fun Loguj zdarzenie
  • setUserId(id) fun Ustaw ID użytkownika
  • setUserProperty(name, value) fun Ustaw właściwość
  • screenView(screenName, screenClass) fun Loguj screen view
  • flush() fun (optional) Wymuś wysłanie
  • reset() fun (optional) Resetuj dane
  • setEnabled(enabled) fun (optional) Włącz/wyłącz
Własny provider
class MixpanelProvider(private val context: Context) : Analytics.AnalyticsProvider {
    override val name = "mixpanel"

    private val mixpanel = MixpanelAPI.getInstance(context, "YOUR_TOKEN")

    override fun log(event: String, params: Map) {
        val props = JSONObject()
        params.forEach { (key, value) ->
            props.put(key, value)
        }
        mixpanel.track(event, props)
    }

    override fun setUserId(id: String?) {
        if (id != null) {
            mixpanel.identify(id)
        } else {
            mixpanel.reset()
        }
    }

    override fun setUserProperty(name: String, value: String?) {
        mixpanel.people.set(name, value)
    }

    override fun screenView(screenName: String, screenClass: String?) {
        log("screen_view", mapOf(
            "screen_name" to screenName,
            "screen_class" to screenClass
        ))
    }

    override fun flush() {
        mixpanel.flush()
    }

    override fun reset() {
        mixpanel.reset()
    }
}

// Użycie
ADict.Analytics.addProvider(MixpanelProvider(context))

💡 Przykłady praktyczne

Kompletna konfiguracja

Pełna konfiguracja analityki
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        ADict.init(this, BuildConfig.DEBUG)

        // Dodaj Firebase Analytics
        ADict.Analytics.addProvider(Analytics.FirebaseProvider(this))

        // Dodaj własny provider
        ADict.Analytics.addProvider(MixpanelProvider(this))

        // Ustaw właściwości użytkownika
        ADict.Analytics.setUserProperties(mapOf(
            "app_version" to BuildConfig.VERSION_NAME,
            "device_model" to Build.MODEL
        ))
    }
}

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Screen view
        ADict.Analytics.screenView("MainActivity", this::class.simpleName)

        // Event logowania
        if (isLoggedIn()) {
            ADict.Analytics.setUserId(currentUser.id)
            ADict.Analytics.setUserProperty("user_type", currentUser.type)
        }
    }

    private fun onPurchaseCompleted(product: Product) {
        ADict.Analytics.logPurchase(
            productId = product.id,
            price = product.price,
            currency = "USD"
        )

        // Dodatkowy event
        ADict.Analytics.log("conversion",
            "type" to "purchase",
            "source" to "product_page"
        )
    }
}

Śledzenie e-commerce

E-commerce tracking
// Wyświetlenie produktu
fun trackProductView(product: Product) {
    ADict.Analytics.log("view_item", mapOf(
        "item_id" to product.id,
        "item_name" to product.name,
        "item_category" to product.category,
        "price" to product.price,
        "currency" to "USD"
    ))
}

// Dodanie do koszyka
fun trackAddToCart(product: Product, quantity: Int) {
    ADict.Analytics.log("add_to_cart", mapOf(
        "item_id" to product.id,
        "item_name" to product.name,
        "price" to product.price,
        "quantity" to quantity,
        "value" to (product.price * quantity)
    ))
}

// Rozpoczęcie checkout
fun trackBeginCheckout(cart: List) {
    ADict.Analytics.log("begin_checkout", mapOf(
        "items" to cart.size,
        "value" to cart.sumOf { it.price * it.quantity },
        "currency" to "USD"
    ))
}

// Zakup
fun trackPurchase(order: Order) {
    ADict.Analytics.logPurchase(
        productId = order.items.first().productId,
        price = order.total,
        currency = "USD",
        extras = mapOf(
            "order_id" to order.id,
            "items_count" to order.items.size,
            "shipping" to order.shippingCost
        )
    )
}

📚 API Reference

Metoda Opis
init() Inicjalizacja (automatycznie przez ADict.init)
addProvider(provider) Dodaj provider analityki
removeProvider(name) Usuń provider
setEnabled(enabled) Włącz/wyłącz analitykę
log(event, params) Zaloguj zdarzenie
screenView(screenName, screenClass) Zaloguj screen view
setUserId(id) Ustaw ID użytkownika
setUserProperty(name, value) Ustaw właściwość użytkownika
logPurchase(...) Loguj zakup
logSubscriptionStart(...) Loguj rozpoczęcie subskrypcji
logAdImpression(...) Loguj wyświetlenie reklamy
logError(...) Loguj błąd
flush() Wymuś wysłanie eventów
reset() Resetuj dane analityczne
getProviders() Pobierz listę providerów