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

Τα συμβάντα είναι η πρώτη ύλη για τα πάντα στο Joryio: τα τμήματα, τα triggers journey, τα φίλτρα καμπάνιας και τα analytics λειτουργούν όλα με τα συμβάντα που στέλνουν οι εφαρμογές σας. Αυτός ο οδηγός καλύπτει τις συμβάσεις και τους μηχανισμούς που μοιράζονται όλα τα SDK - Web, iOS, Android και React Native. Για εγκατάσταση και ρυθμίσεις ανά πλατφόρμα, δείτε τις επιμέρους σελίδες SDK.

Πώς λειτουργεί η παρακολούθηση

Κάθε SDK ακολουθεί το ίδιο pipeline:

Καλείτε track(eventName, properties) στην εφαρμογή σας.
Το SDK τοποθετεί το συμβάν τοπικά σε ουρά (με διατήρηση εκτός σύνδεσης) και το στέλνει σε παρτίδες - από προεπιλογή κάθε 5 δευτερόλεπτα ή κάθε 50 συμβάντα, όποιο συμβεί πρώτο.
Η παρτίδα παραδίδεται στο POST /v1/track/batch, με έλεγχο ταυτότητας μέσω του κλειδιού SDK της εφαρμογής σας (μορφή jry_sdk_<platform>_<random>, ένα για κάθε εφαρμογή - δείτε Επισκόπηση εφαρμογών).
Ο διακομιστής επιλύει τον χρήστη (ανώνυμο ή αναγνωρισμένο), αποθηκεύει τα συμβάντα και τα διανέμει σε τμήματα, triggers journey και analytics.

Μια παρτίδα μπορεί να περιέχει έως 500 συμβάντα. Τα timestamps ορίζονται από το SDK κατά την κλήση· ο διακομιστής δέχεται epoch milliseconds ή συμβολοσειρές ISO-8601 και επιστρέφει στον χρόνο διακομιστή αν το timestamp λείπει ή δεν είναι έγκυρο, ώστε εσφαλμένο ρολόι συσκευής να μην απορρίπτει συμβάν.

Συμβάσεις ονοματοδοσίας συμβάντων

Το όνομα συμβάντος είναι συμβολοσειρά έως 255 χαρακτήρων. Πέρα από αυτό, το Joryio δεν επιβάλλει μορφή - όμως η συνέπεια έχει σημασία, επειδή έτσι βρίσκετε συμβάντα αργότερα σε builders τμημάτων, triggers journey και Event Explorer.

Συστάσεις:

Χρησιμοποιήστε Title Case με κενά. Τα ενσωματωμένα συμβάντα του Joryio ακολουθούν την τυπική ταξινομία e-commerce (Αντικείμενο + ρήμα σε παρελθοντικό χρόνο, Title Case): Product Viewed, Product Added, Checkout Started, Order Completed. Έτσι, προσαρμοσμένα συμβάντα όπως Trial Started και Signup Completed κρατούν τον κατάλογο ομοιόμορφο. Το snake case επίσης λειτουργεί - διαλέξτε μία σύμβαση και τηρήστε την.
Ονομάστε την ενέργεια, όχι το UI. Το Order Completed αντέχει σε redesign· το Green Button Clicked όχι.
Χρησιμοποιήστε αντικείμενο + ρήμα σε παρελθοντικό χρόνο. Subscription Upgraded, Video Played, Search Performed.
Κρατήστε τη μεταβλητότητα στις ιδιότητες, όχι στα ονόματα. Ένα Product Viewed με ιδιότητα category είναι προτιμότερο από πενήντα συμβάντα Viewed <Category>.
Αποφύγετε υπερβολικά γενικά συμβάντα. Το Clicked χωρίς ιδιότητες δεν προσφέρει αξιοποιήσιμη πληροφορία.

Τα ονόματα συμβάντων κάνουν διάκριση πεζών-κεφαλαίων: τα order_placed και Order_Placed είναι δύο διαφορετικά συμβάντα.

Ιδιότητες και τύποι δεδομένων

Οι ιδιότητες είναι αντικείμενο JSON που συνδέεται σε κάθε συμβάν. Γίνεται δεκτή κάθε τιμή JSON:

Τύπος	Παράδειγμα	Σημειώσεις
String	`"currency": "USD"`	Χρησιμοποιήστε το και για ημερομηνίες, ως συμβολοσειρές ISO-8601
Number	`"total": 149.99`	Ακέραιοι και δεκαδικοί
Boolean	`"first_order": true`
Array	`"item_ids": ["SKU-1", "SKU-2"]`
Object	`"shipping": { "method": "express" }`	Επιτρέπονται ένθετα αντικείμενα

Όρια διακομιστή ανά συμβάν:

Όριο	Τιμή
Μήκος ονόματος συμβάντος	255 χαρακτήρες
Συνολικό μέγεθος ιδιοτήτων (σειριοποιημένο JSON)	50 KB
Κλειδιά ιδιοτήτων ανώτερου επιπέδου	200
Βάθος ένθεσης	5 επίπεδα
Συμβάντα ανά αίτημα παρτίδας	500

Συμβάντα που υπερβαίνουν αυτά τα όρια απορρίπτονται. Τα ονόματα ιδιοτήτων ακολουθούν την ίδια συμβουλή: επιλέξτε μια σύμβαση (product_id, όχι άλλοτε productId) και κρατήστε τους τύπους σταθερούς.

Ιδιότητες με πρόθεμα $ (όπως $platform, $session_id, $app_id) προστίθενται αυτόματα - μερικές από τα SDK και άλλες από το pipeline εισαγωγής του Joryio. Θεωρήστε το πρόθεμα δεσμευμένο και μην το χρησιμοποιείτε για δικές σας ιδιότητες.

Κανόνες ονομάτων για χαρακτηριστικά χρήστη

Τα κλειδιά χαρακτηριστικών (το αντικείμενο που δίνετε στο setAttributes / setAttribute) έχουν δύο επιπλέον περιορισμούς, και ένα κλειδί που τους παραβιάζει απορρίπτεται - η υπόλοιπη κλήση αποθηκεύεται κανονικά:

Δεν επιτρέπεται	Γιατί
`.` οπουδήποτε στο κλειδί	Η τελεία διαβάζεται ως διαχωριστικό ΔΙΑΔΡΟΜΗΣ. Το `"profile.email"` θα αποθηκευόταν ως ένθετο `profile: { email }`, οπότε ένα segment στο `profile.email` δεν θα ταίριαζε με τίποτα.
`$` στην αρχή	Δεσμευμένο, όπως και για τις ιδιότητες συμβάντων παραπάνω.
Κενό κλειδί	Δεν υπάρχει τίποτα να αποθηκευτεί.

Τα κλειδιά απορρίπτονται αντί να μετονομάζονται σκόπιμα: η μετονομασία θα ανέφερε επιτυχία ενώ θα έβαζε τα δεδομένα κάπου που δεν ρωτάτε ποτέ.

identify έναντι track

Οι δύο βασικές κλήσεις έχουν διαφορετικό ρόλο:

identify(userId) δηλώνει ποιος είναι ο χρήστης. Συνδέει την τρέχουσα συσκευή/συνεδρία με το σταθερό αναγνωριστικό χρήστη και συγχωνεύει ανώνυμο ιστορικό στο προφίλ. Γνωρίσματα που ορίζονται με setAttributes περιγράφουν τον χρήστη.
track(eventName, properties) δηλώνει τι συνέβη. Οι ιδιότητες περιγράφουν το συμβάν και είναι αμετάβλητες μετά την καταγραφή.

Κανόνες:

Καλέστε identify μόλις γνωρίζετε τον χρήστη - κατά τη σύνδεση και κατά την εκκίνηση εφαρμογής αν αποκαθίσταται συνεδρία. Χρησιμοποιήστε το ίδιο αναγνωριστικό σε κάθε πλατφόρμα ώστε η δραστηριότητα web και mobile να καταλήγει στο ίδιο προφίλ (δείτε Παρακολούθηση πολλών πλατφορμών).
Πριν από το identify, τα συμβάντα καταγράφονται κάτω από ανώνυμο ID. Όταν αναγνωρίσετε αργότερα τον χρήστη, ο διακομιστής συγχωνεύει το ανώνυμο ιστορικό, επομένως τα συμβάντα πριν από την εγγραφή δεν χάνονται.
Χρησιμοποιήστε alias(userId) κατά την εγγραφή για να συνδέσετε ρητά τον ανώνυμο χρήστη με τον νέο λογαριασμό και έπειτα identify(userId).
Βάλτε δεδομένα ανά εμφάνιση σε ιδιότητες συμβάντος (total, coupon) και διαρκή στοιχεία του ατόμου σε γνωρίσματα (plan, lifetime_value).
Καλέστε reset() κατά την αποσύνδεση ώστε ο επόμενος χρήστης στη συσκευή να μην κληρονομήσει το προφίλ.

Το ίδιο συμβάν σε κάθε SDK

Η κλήση track είναι σκόπιμα ίδια σε μορφή σε όλα τα SDK. Ακολουθεί το ίδιο συμβάν Order Completed και στις τέσσερις πλατφόρμες.

Web (JS)
iOS (Swift)
Android (Kotlin)
React Native

import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

Joryio.shared.track("Order Completed", properties: [
    "order_id": "ORD-2024-001",
    "total": 149.99,
    "currency": "USD",
    "item_count": 3,
    "coupon": "SAVE10"
])

Joryio.track("Order Completed", mapOf(
    "order_id" to "ORD-2024-001",
    "total" to 149.99,
    "currency" to "USD",
    "item_count" to 3,
    "coupon" to "SAVE10"
))

import Joryio from '@joryio/react-native-sdk';

Joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

Επειδή το όνομα και οι ιδιότητες είναι ίδιες, μία συνθήκη τμήματος ή trigger journey ταιριάζει με το συμβάν ανεξάρτητα από την πλατφόρμα προέλευσής του.

Για τυπική δραστηριότητα e-commerce (προβολές προϊόντων, καλάθια, checkout, παραγγελίες), προτιμήστε τους ενσωματωμένους e-commerce trackers των SDK - εκπέμπουν τα τυποποιημένα ονόματα συμβάντων που περιμένουν οι λειτουργίες e-commerce του Joryio. Δείτε τον δια-SDK οδηγό E-Commerce Tracking.

Τι συμβαίνει στον διακομιστή

Μόλις γίνει δεκτή μια παρτίδα, κάθε συμβάν:

Αποθηκεύεται στο analytics store, συνδεδεμένο με το επιλυμένο προφίλ χρήστη.
Αξιολογείται έναντι triggers journey. Journey με trigger εισόδου που ταιριάζει με το όνομα συμβάντος εγγράφει τον χρήστη αμέσως.
Τροφοδοτεί τμήματα. Οι συνθήκες τμημάτων βάσει συμβάντος ενημερώνονται από τη ροή συμβάντων.
Εμφανίζεται στα analytics - στο Event Explorer, τα funnels και τα analytics ανά εφαρμογή.
Μπορεί να ενημερώσει το προφίλ. Για παράδειγμα, συμβάντα Session Start ενημερώνουν την εγγραφή συσκευής του χρήστη και γνωρίσματα όπως country.

Δύο συμπεριφορές διακομιστή που αξίζει να γνωρίζετε:

Σήμανση bot. Αιτήματα από γνωστά bot user agents επισημαίνονται· κλήσεις που μεταβάλλουν προφίλ, όπως identify και setAttributes, παραλείπονται για bots.
Επιεικής επικύρωση. Άγνωστα επιπλέον πεδία στο payload αφαιρούνται αντί να απορρίπτονται, ώστε ασυμφωνία έκδοσης SDK να μη χάνει τα συμβάντα σας.

Επαλήθευση και εντοπισμός σφαλμάτων

Ελέγξτε ότι έφτασε ένα συμβάν

Ενεργοποιήστε το συμβάν στην εφαρμογή σας.
Στο dashboard του Joryio, ανοίξτε Analytics → Event Explorer. Φιλτράρετε με όνομα συμβάντος· θα πρέπει να εμφανιστεί μέσα σε δευτερόλεπτα από την αποστολή της παρτίδας από το SDK.
Για προβολή ανά εφαρμογή, ανοίξτε Ρυθμίσεις → Εφαρμογές και επιλέξτε View Analytics στην εφαρμογή.

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

Εξαναγκάστε αποστολή. Τα συμβάντα ομαδοποιούνται· καλέστε flush() για άμεση αποστολή.
Ενεργοποιήστε debug logging. Κάθε SDK διαθέτει επιλογή enableDebug που καταγράφει κάθε συμβάν στην ουρά και αίτημα δικτύου.
Ελέγξτε το κλειδί SDK. Πρέπει να ταιριάζει με την πλατφόρμα: jry_sdk_web_..., jry_sdk_ios_..., jry_sdk_android_.... Ένα αναδημιουργημένο κλειδί ακυρώνει αμέσως το παλιό.
Ελέγξτε ότι η εφαρμογή είναι ενεργή στις Ρυθμίσεις → Εφαρμογές.
Παρακολουθήστε την απόκριση δικτύου. Η απόκριση παρτίδας περιλαμβάνει success και, σε μερική αποτυχία, failedIndices.
Μόνο Web: τα endpoints επιτρέπουν κάθε origin (Access-Control-Allow-Origin: *), επομένως τα σφάλματα CORS συνήθως δείχνουν λάθος apiEndpoint ή επέκταση προγράμματος περιήγησης.
Δοκιμή από automation; Θυμηθείτε τη σήμανση bot παραπάνω - επαληθεύστε με πραγματικό πρόγραμμα περιήγησης ή συσκευή.

Πώς λειτουργεί η παρακολούθηση​

Συμβάσεις ονοματοδοσίας συμβάντων​

Ιδιότητες και τύποι δεδομένων​

Κανόνες ονομάτων για χαρακτηριστικά χρήστη​

identify έναντι track​

Το ίδιο συμβάν σε κάθε SDK​

Τι συμβαίνει στον διακομιστή​

Επαλήθευση και εντοπισμός σφαλμάτων​

Ελέγξτε ότι έφτασε ένα συμβάν​

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

Σχετικά​