Μετάβαση στο κύριο περιεχόμενο

Ενσωμάτωση Android SDK

Εγγενές Android SDK για παρακολούθηση συμβάντων, διαχείριση συνεδριών χρηστών, αποστολή push notifications μέσω FCM και εμφάνιση μηνυμάτων εντός εφαρμογής.

Δυνατότητες

  • Ελαφρύ - Ελάχιστο αποτύπωμα
  • Γρήγορο - Βελτιστοποιημένο για απόδοση
  • Υποστήριξη εκτός σύνδεσης - Ουρά συμβάντων βασισμένη σε SQLite
  • Αυτόματη επανάληψη - Exponential backoff σε αποτυχίες
  • Ομαδοποίηση - Αποτελεσματική ομαδοποίηση συμβάντων (50 συμβάντα / 5 δευτ.)
  • Μηνύματα εντός εφαρμογής - native και HTML μηνύματα, 5 τύποι, με frequency capping
  • Push Notifications - Firebase Cloud Messaging (FCM)
  • Απόρρητο πρώτα - Συμβατό με GDPR, σέβεται τη συγκατάθεση χρήστη
  • Android 6.0+ - Υποστήριξη API 23+

Απαιτήσεις

  • Android 6.0 (επίπεδο API 23) ή νεότερο - το κατώφλι για κρυπτογραφημένη αποθήκευση (EncryptedSharedPreferences) και το ίδιο ελάχιστο που απαιτεί το Firebase Cloud Messaging
  • Kotlin 1.9.20 ή νεότερο
  • Gradle 8.0 ή νεότερο

Τοπική ρύθμιση SDK

Για τοπικά builds, ορίστε τη διαδρομή Android SDK στο local.properties:

sdk.dir=/Users/your-user/Library/Android/sdk

Εναλλακτικά, εξαγάγετε ANDROID_HOME/ANDROID_SDK_ROOT πριν εκτελέσετε Gradle.

Εγκατάσταση

Gradle (συνιστάται)

Προσθέστε στο build.gradle.kts:

Το SDK διατίθεται σε δύο artifacts. Προσθέστε ένα από αυτά - το artifact UI περιέχει το βασικό, οπότε ποτέ δεν δηλώνετε και τα δύο:

dependencies {
// Τα πάντα, μαζί με την εμφάνιση in-app μηνυμάτων. Ξεκινήστε εδώ.
implementation("io.joryio:joryio-android-ui:1.0.0")
}
dependencies {
// Μόνο tracking, ταυτότητα και push - χωρίς in-app απόδοση και χωρίς
// WebView. Επιλέξτε το αν η εφαρμογή δεν χρησιμοποιεί in-app μηνύματα ή αν
// τα αποδίδετε μόνοι σας.
implementation("io.joryio:joryio-android:1.0.0")
}

Ή με Groovy (build.gradle):

dependencies {
implementation 'io.joryio:joryio-android-ui:1.0.0'
}
Ποιο από τα δύο;

Το joryio-android-ui εξαρτάται από το joryio-android, οπότε μία γραμμή σας δίνει και τα δύο και δεν μπορούν να αποκλίνουν - δηλώνετε μόνο μία έκδοση.

Πάρτε μόνο το βασικό artifact όταν η εφαρμογή δεν χρειάζεται in-app μηνύματα ή όταν ένας έλεγχος ασφαλείας αντιτίθεται στη σύνδεση WebView. Τα in-app μηνύματα απλώς δεν θα εμφανίζονται· όλα τα υπόλοιπα λειτουργούν κανονικά.

Γρήγορη εκκίνηση

1. Αρχικοποιήστε το SDK

Στην κλάση Application:

import io.joryio.sdk.Joryio
import io.joryio.sdk.JoryioConfig

class MyApplication : Application() {
override fun onCreate() {
super.onCreate()

// Initialize with your SDK key
Joryio.initialize(
context = this,
sdkKey = "jry_sdk_android_YOUR_SDK_KEY",
apiHost = "api-eu1.joryio.com"
)
}
}
Εύρεση του κλειδιού SDK

Βρείτε το κλειδί SDK στο dashboard του Joryio στις Ρυθμίσεις → Εφαρμογές → [Η εφαρμογή σας] → SDK Keys.

2. Παρακολουθήστε συμβάντα

// Basic event
Joryio.track("Button Tapped")

// Event with properties
Joryio.track("Product Viewed", mapOf(
"product_id" to "abc123",
"product_name" to "Wireless Headphones",
"price" to 99.99,
"category" to "Electronics"
))

// Screen view
Joryio.trackScreen("ProductDetail", mapOf(
"product_id" to "abc123"
))

3. Αναγνωρίστε χρήστες

// Identify a user
Joryio.identify("user-123")
Joryio.getInstance().setAttributes(mapOf(
"email" to "user@example.com",
"name" to "John Doe",
"plan" to "premium"
))

// Set attributes later
Joryio.setAttribute("last_purchase", Date())
Joryio.incrementAttribute("lifetime_value", 99.99)

// On logout
Joryio.reset()

Αυτόματα δεδομένα συνεδρίας

Το Android SDK εμπλουτίζει τα συμβάντα Session Start με δεδομένα συσκευής και περιβάλλοντος:

  • $device_id
  • $platform (android)
  • $manufacturer / $model
  • $os_name / $os_version / $os_sdk_int
  • $app_version / $build_number
  • $package_name
  • $screen_width / $screen_height
  • $locale
  • $language / $languages
  • $timezone
  • country (ISO-3166-1 alpha-2, προέρχεται από IP κατά την έναρξη συνεδρίας)

Push Notifications

Ενεργοποιήστε push notifications με Firebase Cloud Messaging (FCM).

1. Προσθέστε Firebase στο έργο σας

Ακολουθήστε τον οδηγό ρύθμισης Firebase για να προσθέσετε Firebase στο Android έργο σας.

2. Προσθέστε service στο AndroidManifest.xml

<service
android:name="io.joryio.sdk.push.JoryioFirebaseMessagingService"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>

3. Εγγραφή για Push Notifications

import com.google.firebase.messaging.FirebaseMessaging

// Get FCM token and register
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
if (task.isSuccessful) {
val token = task.result
Joryio.getInstance().registerPushToken(token)
}
}

// Check if push is enabled
val isEnabled = Joryio.getInstance().isPushEnabled()

// Unregister when needed
Joryio.getInstance().unregisterPush()

Αντιμετώπιση προβλημάτων

Τα συμβάντα δεν εμφανίζονται

  1. Ελέγξτε ότι το κλειδί SDK είναι σωστό: jry_sdk_android_*
  2. Ενεργοποιήστε debug logging: enableDebug = true
  3. Ελέγξτε το logcat για σφάλματα
  4. Επαληθεύστε τα δικαιώματα δικτύου στο manifest
  5. Καλέστε flush() για άμεση αποστολή

Το push δεν λειτουργεί

  1. Επαληθεύστε ότι το Firebase είναι ρυθμισμένο σωστά
  2. Ελέγξτε ότι το Firebase service account JSON έχει μεταφορτωθεί στο dashboard
  3. Βεβαιωθείτε ότι το device token έχει καταχωριστεί
  4. Δοκιμάστε πρώτα με το Firebase Console

Σφάλματα build

  1. Βεβαιωθείτε ότι η ελάχιστη έκδοση SDK είναι 23
  2. Συγχρονίστε τις εξαρτήσεις Gradle
  3. Εκκαθαρίστε και ξανακάντε build στο έργο

Παρακολούθηση E-Commerce

Το Android SDK περιλαμβάνει ενσωματωμένο e-commerce tracker για συμβάντα προϊόντων, καλαθιού, checkout και παραγγελιών. Δείτε τον δια-SDK οδηγό E-Commerce Tracking για το πλήρες API με παραδείγματα Kotlin.

Επόμενα βήματα

4. Ρύθμιση FCM στο Dashboard

Για να στείλετε push notifications, ρυθμίστε τα διαπιστευτήρια Firebase:

  1. Μεταβείτε στις Ρυθμίσεις → Εφαρμογές → [Η εφαρμογή σας]
  2. Ανοίξτε τις ρυθμίσεις push notifications
  3. Ανεβάστε το Firebase service account JSON (από το Firebase console: Project settings → Service accounts → Generate new private key)
  4. Αποθηκεύστε τη ρύθμιση

Μηνύματα εντός εφαρμογής

Το SDK εμφανίζει τα μηνύματα in-app για εσάς. Μετά την αρχικοποίηση, οι επιλέξιμες καμπάνιες εμφανίζονται μόνες τους και οι εμφανίσεις, τα κλικ και οι απορρίψεις καταγράφονται αυτόματα - δεν χρειάζεται καμία σύνδεση.

Tokens παράδοσης (delivery tokens)

Όταν ο διακομιστής σερβίρει μια επιλέξιμη καμπάνια, εκδίδει επίσης ένα υπογεγραμμένο token παράδοσης μικρής διάρκειας. Το SDK το επιστρέφει όταν αναφέρει εμφάνιση, κλικ ή απόρριψη, και ο διακομιστής επαληθεύει την υπογραφή πριν καταγράψει οτιδήποτε.

Δεν χρειάζεται να κάνετε τίποτα - το SDK το χειρίζεται για εσάς. Τεκμηριώνεται επειδή αλλάζει τι συμβαίνει σε έναν client που δεν στέλνει token:

POST /v1/in-app/track   (no deliveryToken)
{ "success": false, "error": "A delivery token is required" }

Το token είναι αυτό που κάνει μια εμφάνιση αξιόπιστη: χωρίς αυτό, οποιοσδήποτε κατέχει το SDK key - το οποίο περιλαμβάνεται σε κάθε εφαρμογή και σελίδα - θα μπορούσε να αναφέρει εμφανίσεις και κλικ για μια καμπάνια που δεν εμφανίστηκε ποτέ, και τα δεδομένα σας θα τα μετρούσαν.

Αν οι εμφανίσεις in-app σταματήσουν να καταγράφονται, ελέγξτε ότι η εφαρμογή έχει χτιστεί με τρέχουσα έκδοση του SDK: μια έκδοση από πριν υπάρξουν τα tokens παράδοσης δεν στέλνει token και ο διακομιστής θα απορρίψει τις εμφανίσεις της.

Δύο είδη περιεχομένου

Κάθε καμπάνια φτάνει σε μία από δύο μορφές περιεχομένου και το SDK αποδίδει την καθεμία διαφορετικά:

ΠεριεχόμενοΤι είναιΠώς αποδίδεται
NativeΔομημένα δεδομένα - τίτλος, κείμενο, εικόνα, κουμπιάΠραγματικά Android views, με το θέμα, τις γραμματοσειρές, τη σκοτεινή λειτουργία και το TalkBack της εφαρμογής σας. Χωρίς WebView.
HTMLΚώδικας HTML, CSS και JavaScript γραμμένος από τον συντάκτηΈνα WebView μέσα στο μήνυμα.

Ενεργοποίηση μηνυμάτων HTML

Τα μηνύματα HTML είναι απενεργοποιημένα από προεπιλογή. Ένα μήνυμα HTML εκτελεί JavaScript γραμμένη από τον συντάκτη μέσα στην εφαρμογή σας, οπότε η ενεργοποίηση είναι απόφαση της ομάδας της εφαρμογής - όχι κάτι που ενεργοποιείται από μια πλατφόρμα μάρκετινγκ:

val config = JoryioConfig(
allowHtmlJsInAppMessages = true // προεπιλογή: false
)

Joryio.initialize(
context = this,
sdkKey = "jry_sdk_android_YOUR_KEY",
apiHost = "api-eu1.joryio.com",
config = config
)

Αφήνοντάς το απενεργοποιημένο δεν απενεργοποιείτε τα in-app μηνύματα. Τα native μηνύματα συνεχίζουν να εμφανίζονται, επειδή είναι δεδομένα που η εφαρμογή σας σχεδιάζει με τα δικά της views - χωρίς κανέναν διερμηνέα. Οι καμπάνιες HTML παραλείπονται και καταγράφονται, ώστε μια εφαρμογή που δεν το έχει ενεργοποιήσει να μην δείχνει τίποτα αντί για ένα χαλασμένο μήνυμα.

Αν η πολιτική ασφαλείας σας απαγορεύει την εκτέλεση συντεταγμένου HTML εντός της διεργασίας, αφήστε το απενεργοποιημένο και συντάξτε τις καμπάνιες σας ως native μηνύματα.

Αναλαμβάνοντας εσείς την απόδοση

Ορίστε ένα callback για να σχεδιάσετε το δικό σας UI. Υπερισχύει της απόδοσης του SDK, οπότε δεν θα λάβετε δύο αντίγραφα του μηνύματος:

Joryio.getInstance().setInAppMessageCallback { campaign ->
showInAppMessage(campaign) // το δικό σας UI
}

// Αναφέρετε τι συνέβη - το SDK καταγράφει αυτόματα μόνο όσα εμφανίζει το ίδιο
Joryio.getInstance().trackInAppImpression(campaignId, "viewed")
Joryio.getInstance().trackInAppImpression(campaignId, "clicked")
Joryio.getInstance().trackInAppImpression(campaignId, "dismissed")

Απόδοση των μηνυμάτων μόνοι σας

Το SDK σχεδιάζει τα native μηνύματα, αλλά μπορείτε να αναλάβετε πλήρως - το αντίστοιχο του custom view factory:

Joryio.getInstance().setInAppMessageCallback { campaign ->
// σχεδιάστε το όπως θέλετε
}

Ο ορισμός callback αντικαθιστά τον ενσωματωμένο renderer αντί να τρέχει παράλληλα, οπότε το μήνυμα εμφανίζεται μία φορά, όχι δύο.

Το campaign.content είναι ήδη έτοιμο - το Liquid αποδίδεται στον διακομιστή και τα native πεδία φτάνουν ως απλό κείμενο (μην τα δίνετε σε WebView: δεν έχουν HTML-escape ακριβώς επειδή προορίζονται για TextView). Καταγράψτε ό,τι εμφανίζετε με trackInAppImpression(campaignId, "impression" | "clicked" | "dismissed").

Τύποι μηνυμάτων

Το SDK υποστηρίζει 5 τύπους μηνυμάτων:

  1. Modal - Στο κέντρο της οθόνης με σκίαση
  2. Banner - Στο επάνω μέρος της οθόνης
  3. Slide-Up - Μικρή ειδοποίηση από κάτω
  4. Full-Screen - Μήνυμα που καταλαμβάνει την οθόνη
  5. Custom - Η εφαρμογή σας αποφασίζει τη θέση

Επιλογές ρυθμίσεων

Προσαρμόστε τη συμπεριφορά του SDK με JoryioConfig:

val config = JoryioConfig(
// Initial user ID (optional)
userId = "user-123",

// Event batching
batchSize = 50, // Events per batch
flushInterval = 5000, // Flush interval in ms (5s)

// Session management
sessionTimeout = 1800000, // Session timeout in ms (30 min)
trackSessionStart = true, // Auto-track session start

// Network retry
maxRetries = 3, // Max retry attempts

// Privacy controls
optOut = false, // Opt out of tracking
trackingConsent = TrackingConsent.GRANTED,

// Debugging
enableDebug = false, // Enable debug logging
logLevel = LogLevel.ERROR // Log level
)

Joryio.initialize(
context = this,
sdkKey = "jry_sdk_android_YOUR_KEY",
apiHost = "api-eu1.joryio.com",
config = config
)

Συγκατάθεση παρακολούθησης

enum class TrackingConsent {
GRANTED, // Full tracking allowed
PENDING, // Waiting for user decision
DENIED // User denied tracking
}

Επίπεδα log

enum class LogLevel {
VERBOSE, // All logs
DEBUG, // Debug and above
INFO, // Info and above
WARN, // Warnings and errors
ERROR // Errors only
}

Προηγμένες δυνατότητες

Διαχείριση συνεδριών

Οι συνεδρίες παρακολουθούν αυτόματα την αλληλεπίδραση χρήστη:

// Sessions are managed automatically with 30-minute timeout
// Get current session ID
val sessionId = Joryio.getInstance().getSessionId()

// Sessions refresh on user activity

Γνωρίσματα χρήστη

// Set multiple attributes
Joryio.getInstance().setAttributes(mapOf(
"age" to 28,
"city" to "San Francisco",
"premium" to true
))

// Set single attribute
Joryio.setAttribute("language", "en")

// Increment numeric attribute
Joryio.incrementAttribute("page_views", 1)
Joryio.incrementAttribute("total_spent", 29.99)

// Remove attribute
Joryio.getInstance().unsetAttribute("temporary_flag")

Έλεγχοι απορρήτου

// Stop collecting. PERSISTED - survives an app restart.
Joryio.getInstance().optOut()

// Opt back in
Joryio.getInstance().optIn()

// Check opt-out status
if Joryio.getInstance().isUserOptedOut() {
print("User has opted out")
}

// Delete everything the SDK stored on this device.
// SEPARATE from optOut(): "stop collecting" and "delete what you have" are
// different requests. This is the one an erasure request needs. It does NOT
// opt the user out - call optOut() as well if that is also intended.
Joryio.getInstance().wipeData()

// Get identity info
val (userId, anonymousId) = Joryio.getInstance().getIdentity()
println("User: ${userId ?: "anonymous"}, Anonymous ID: $anonymousId")

What optOut() does, precisely:

stops collectionyes - track, identify and setAttributes all become no-ops
survives a restartyes - the flag is stored on the device and read before anything is collected
drops what is already queuedyes - queued events and un-acked attribute writes are discarded, not delivered later
tells the serveryes - one final $tracking_opted_out profile attribute, best-effort, sent while sending is still permitted
deletes stored datano - use wipeData()

The $tracking_opted_out attribute is a record, not enforcement: it lands on the profile so campaigns can exclude on it. Server-side suppression is a separate setting.

σημείωση

Ενημερώθηκε στα Αγγλικά - μετάφραση σε εκκρεμότητα.

Μη αυτόματη αποστολή ουράς

// Flush events immediately
Joryio.flush()

// Useful before app termination
override fun onDestroy() {
super.onDestroy()
Joryio.flush()
}

Βέλτιστες πρακτικές

1. Αρχικοποιήστε νωρίς

Αρχικοποιήστε στην κλάση Application:

class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Joryio.initialize(
context = this,
sdkKey = "jry_sdk_android_YOUR_KEY",
apiHost = "api-eu1.joryio.com"
)
}
}

2. Παρακολουθήστε προβολές οθόνης

Χρησιμοποιήστε παρακολούθηση οθόνης για πλοήγηση:

override fun onResume() {
super.onResume()
Joryio.trackScreen(this::class.simpleName ?: "Unknown")
}

3. Χειριστείτε την αποσύνδεση χρήστη

Κάνετε πάντα reset κατά την αποσύνδεση:

fun logout() {
// Clear user session
clearUserSession()

// Reset SDK
Joryio.reset()
}

Αναφορά API

Παρακολούθηση συμβάντων

// Track event
Joryio.track(
eventName: String,
properties: Map<String, Any?> = emptyMap()
)

// Track screen view
Joryio.trackScreen(
screenName: String,
properties: Map<String, Any?> = emptyMap()
)

// Flush events immediately
Joryio.flush()

Ταυτότητα χρήστη

// Identify user
Joryio.identify(
userId: String
)

// Set attributes
Joryio.getInstance().setAttributes(
attributes: UserAttributes
)

// Alias user
Joryio.alias(userId: String)

// Reset user (logout)
Joryio.reset()

// Get IDs
Joryio.getInstance().getAnonymousId(): String
Joryio.getInstance().getUserId(): String?
Joryio.getInstance().getSessionId(): String

Μηνύματα εντός εφαρμογής

// Set message callback
Joryio.getInstance().setInAppMessageCallback { campaign ->
// Handle message display
}

// Track impressions
Joryio.getInstance().trackInAppImpression(
campaignId: String,
action: String
)

Push Notifications

// Register token
Joryio.getInstance().registerPushToken(token: String)

// Check status
Joryio.getInstance().isPushEnabled(): Boolean

// Unregister
Joryio.getInstance().unregisterPush()

API δοκιμών και διαγνωστικών

Δύο ομάδες, και η διαφορά έχει σημασία.

API δοκιμών - αγνοούνται εκτός αν το enableDebug είναι ενεργό. Αλλάζουν ζωντανή κατάσταση, οπότε μια αδέσποτη κλήση σε build παραγωγής θα αλλοίωνε πραγματικά όρια συχνότητας και αναφορές.

ΜέθοδοςΤι κάνει
resetDisplayedCampaigns()Ξεχνά ποιες καμπάνιες in-app έχουν ήδη εμφανιστεί. Η κατάσταση συχνότητας κρατιέται στη συσκευή, οπότε μια αλλαγή στον διακομιστή ΔΕΝ θα την εμφανίσει ξανά.
evaluateInAppCampaigns()Επαναλαμβάνει την απόφαση εμφάνισης χωρίς κλήση δικτύου.

Διαγνωστικά API - πάντα διαθέσιμα, και στην παραγωγή. Μόνο διαβάζουν κατάσταση, οπότε δεν μπορούν να βλάψουν τίποτα.

ΜέθοδοςΑπαντά
getQueueSize()Πόσα συμβάντα περιμένουν αποστολή;
currentApiEndpoint / lastTransportErrorΣε ποιον διακομιστή μιλάμε και απέτυχε η τελευταία κλήση;

Τα getIdentity(), getSessionInfo() και getDeviceToken() ΔΕΝ ανήκουν σε καμία ομάδα - είναι κανονικό API. Η ανάγνωση της ταυτότητας της συσκευής είναι φυσιολογική ενέργεια για μια εφαρμογή.

Attribute delivery

setAttributes is durable. A write is queued until the server acknowledges it, so an attribute set while the device is offline is delivered when connectivity returns rather than dropped.

  • Retried on the next setAttributes, on foreground, and before an in-app sync.
  • Batched - a burst of calls becomes one request (800ms window). A single write still goes out promptly.
  • Persisted in the platform's encrypted store (iOS Keychain, Android EncryptedSharedPreferences), so a write survives the process being killed. Cleared the moment the server acks, and purged by optOut() and wipeData().

Attributes are also used for in-app targeting. The server profile is authoritative: only writes the server has not yet acknowledged can override it, which is what keeps two devices belonging to the same contact from disagreeing about who that contact is.

σημείωση

Ενημερώθηκε στα Αγγλικά - μετάφραση σε εκκρεμότητα.