Analytics - ADict Library

📖 PrzeglądOverview

Moduł Analytics to agregator analityki umożliwiający wysyłanie zdarzeń do wielu providerów jednocześnie. Jeden log → wszystkie providery.The Analytics module is an analytics aggregator enabling sending events to multiple providers simultaneously. One log → all providers.

💡 Automatyczna inicjalizacja: W trybie debug automatycznie dodawany jest ConsoleProvider, który loguje wszystkie eventy do konsoli.ConsoleProvider that logs all events to the console.

Szybki przykładQuick Example

// 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 provideryBuilt-in providers

FirebaseProvider

Provider dla Firebase Analytics.Provider for Firebase Analytics.

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

ConsoleProvider

Provider debugowy logujący do konsoli (automatycznie dodawany w debug).Debug provider logging to console (automatically added in debug).

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

addProvider(provider: AnalyticsProvider)

Dodaj provider analityki.Add an analytics provider.

ParametryParameters:

provider: AnalyticsProvider - Implementacja interfejsu AnalyticsProvider

removeProvider(name: String)

Usuń provider po nazwie.Remove provider by name.

setEnabled(enabled: Boolean)

Włącz/wyłącz całą analitykę.Enable/disable all analytics.

getProviders(): List<String>

Pobierz listę aktywnych providerów.Get the list of active providers.

📝 Logowanie zdarzeńEvent Logging

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

Zaloguj zdarzenie z parametrami.Log an event with parameters.

ParametryParameters:

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ść.Log an event with key-value pairs.

screenView(screenName: String, screenClass: String?)

Zaloguj wyświetlenie ekranu.Log a screen view.

Logowanie zdarzeńLogging Events

// 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żytkownikUser

setUserId(id: String?)

Ustaw ID użytkownika dla wszystkich providerów.Set user ID for all providers.

setUserProperty(name: String, value: Any?)

Ustaw właściwość użytkownika.Set user property.

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

Ustaw wiele właściwości jednocześnie.Set multiple properties at once.

Właściwości użytkownikaUser Properties

// 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 eventyPredefined Events

Analytics oferuje gotowe metody dla często używanych zdarzeń:Analytics offers ready-made methods for commonly used events:

logPurchase(productId, price, currency, extras)

Zakup produktu.Product purchase.

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.Subscription start.

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

logAdImpression(adType, adUnit, provider, zone)

WyświetlenieImpression reklamy.

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

logAdClick(adType, adUnit, provider)

KliknięcieClick w reklamę.

logError(errorType, message, extras)

Błąd w aplikacji.App error.

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.Content sharing.

logSearch(query, resultsCount)

Wyszukiwanie.Search.

logTutorialComplete(tutorialId)

Ukończenie tutoriala.Tutorial completion.

logLevelComplete(level, score)

Ukończenie poziomu w grze.Game level completion.

🔧 Własny providerCustom Provider

Możesz stworzyć własny provider implementując interfejsYou can create a custom provider by implementing the interface AnalyticsProvider:

interface AnalyticsProvider

name String Unikalna nazwa provideraUnique provider name
log(event, params) fun Loguj zdarzenieLog event
setUserId(id) fun Ustaw ID użytkownikaSet user ID
setUserProperty(name, value) fun Ustaw właściwośćSet property
screenView(screenName, screenClass) fun Loguj screen viewLog screen view
flush() fun (optional) Wymuś wysłanieForce send
reset() fun (optional) Resetuj daneReset data
setEnabled(enabled) fun (optional) Włącz/wyłączEnable/disable

Własny providerCustom 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ładyExamples praktyczne

Kompletna konfiguracjaComplete Configuration

Pełna konfiguracjaFull Configuration 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-commerceE-commerce Tracking

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

MetodaMethod	OpisDescription
`init()`	Inicjalizacja (automatycznie przez ADict.init)
`addProvider(provider)`	Dodaj provider analityki
`removeProvider(name)`	Usuń providerRemove provider
`setEnabled(enabled)`	Włącz/wyłączEnable/disable analitykę
`log(event, params)`	Zaloguj zdarzenie
`screenView(screenName, screenClass)`	Zaloguj screen view
`setUserId(id)`	Ustaw ID użytkownikaSet user ID
`setUserProperty(name, value)`	Ustaw właściwośćSet property użytkownika
`logPurchase(...)`	Loguj zakup
`logSubscriptionStart(...)`	Loguj rozpoczęcie subskrypcjiLog subscription start
`logAdImpression(...)`	Loguj wyświetlenie reklamyLog ad impression
`logError(...)`	Loguj błądLog error
`flush()`	Wymuś wysłanieForce send eventów
`reset()`	Resetuj daneReset data analityczne
`getProviders()`	Pobierz listę providerówGet list of providers