Analytics
Agregator analityki - jeden interfejs dla wielu providerów
📖 Przegląd
Moduł Analytics to agregator analityki umożliwiający wysyłanie zdarzeń
do wielu providerów jednocześnie. Jeden log → wszystkie providery.
// 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 zdarzeniaparams: 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.
// 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.
// 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
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
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
// 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 |