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

Το Joryio Web SDK σάς επιτρέπει να παρακολουθείτε τη συμπεριφορά χρηστών, να στέλνετε συμβάντα και να διαχειρίζεστε προφίλ χρηστών στον ιστότοπό σας.

Εγκατάσταση

Μέσω npm/yarn

npm install @joryio/web-sdk
# or
yarn add @joryio/web-sdk

Μέσω CDN

Μπορείτε να φορτώσετε το SDK από το CDN του Joryio χρησιμοποιώντας είτε μια καρφιτσωμένη έκδοση (συνιστάται για παραγωγή) είτε το κανάλι latest (αυτόματη αναβάθμιση, για ανάπτυξη / εσωτερική χρήση).

<!-- Pinned: production-safe, immutable cache. You upgrade by changing the URL. -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>

<!-- Latest: auto-upgrades within ~5 minutes of every SDK release. -->
<script src="https://cdn.joryio.com/sdk/web/latest/joryio.min.js"></script>

Ποια επιλογή να χρησιμοποιήσετε

Καρφιτσωμένη (/1.0.0/) - για ιστότοπους παραγωγής όπου θέλετε προβλέψιμο έλεγχο του χρόνου αναβάθμισης του SDK. Το bundle σερβίρεται με αμετάβλητη cache ενός έτους, ώστε οι επισκέπτες που επιστρέφουν να το λαμβάνουν μία φορά και να μη γίνεται δικτυακό αίτημα στις επόμενες φορτώσεις σελίδας.
Latest - για εσωτερικά dashboards, staging και μικρούς πελάτες που θέλουν να λαμβάνουν αυτόματα ενημερώσεις SDK. Αποθηκεύεται στην cache για 5 λεπτά, με παράθυρο stale-while-revalidate μίας ώρας, ώστε οι νέες εκδόσεις να διαδίδονται μέσα σε λίγα λεπτά από την κυκλοφορία τους.

Αναβάθμιση καρφιτσωμένης ενσωμάτωσης. Όταν το Joryio κυκλοφορεί νέα έκδοση SDK, αλλάξτε τον αριθμό στο snippet:

<!-- Before -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>
<!-- After -->
<script src="https://cdn.joryio.com/sdk/web/1.1.0/joryio.min.js"></script>

Το πρόγραμμα περιήγησης αντιμετωπίζει το νέο URL ως νέο αρχείο, το αποθηκεύει αμετάβλητα στην cache και εκτελεί το νέο SDK. Οι παλιές εγγραφές cache παραμένουν μέχρι να λήξει το TTL τους ή ο χρήστης να εκκαθαρίσει την cache.

Επαλήθευση της έκδοσης που εκτελείται. Κάθε απόκριση SDK περιλαμβάνει δύο διαγνωστικές κεφαλίδες:

Κεφαλίδα	Παράδειγμα	Σημασία
`X-SDK-Version-Served`	`1.0.0`	Η έκδοση SDK που έχει αναπτυχθεί αυτή τη στιγμή από την πλευρά του Joryio.
`X-SDK-Version-Requested`	`1.0.0`	Η έκδοση που ζητήθηκε από το URL του snippet (ορίζεται μόνο σε καρφιτσωμένες διαδρομές).

Ανοίξτε DevTools → Network → βρείτε το joryio.min.js → Response Headers. Αν το Requested διαφέρει από το Served, το HTML snippet σας δείχνει σε παλαιότερο URL έκδοσης από αυτό που είναι ενεργό - οι επισκέπτες ίσως λαμβάνουν το νεότερο bundle αποθηκευμένο με το παλαιότερο URL.

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

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

Αρχικά, αρχικοποιήστε το SDK με το κλειδί SDK σας. Θα το βρείτε στο dashboard του Joryio, στις Ρυθμίσεις → Εφαρμογές.

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

// Initialize the SDK
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
  enableDebug: false, // Enable debug logging in development
});

Όταν το φορτώνετε από CDN αντί για npm, η ίδια κλάση είναι διαθέσιμη ως window.Joryio:

const joryio = new Joryio({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
});

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

Αναγνωρίστε χρήστες όταν εγγράφονται ή συνδέονται:

// Identify a user
joryio.identify('user_123');

// Set profile attributes separately
joryio.setAttributes({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  plan: 'premium',
  signupDate: '2024-01-15',
});

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

Παρακολουθήστε ενέργειες και συμπεριφορά χρηστών:

// Track a custom event
joryio.track('Product Viewed', {
  product_id: 'prod_123',
  product_name: 'Premium Plan',
  price: 99.99,
  currency: 'USD',
});

// Track page views
joryio.track('Page Viewed', {
  page: '/pricing',
  title: 'Pricing Page',
  category: 'Marketing',
});

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

Επιλογή	Τύπος	Προεπιλογή	Περιγραφή
`sdkKey`	string	Απαιτείται	Το κλειδί SDK σας από το dashboard του Joryio
`apiEndpoint`	string	`https://api-eu1.joryio.com`	Παράκαμψη του βασικού URL API (προεπιλογή `https://api-eu1.joryio.com`). Απαιτείται μόνο για δοκιμές ή αποκλειστικές αναπτύξεις.
`enableDebug`	boolean	`false`	Ενεργοποιεί καταγραφή εντοπισμού σφαλμάτων στην κονσόλα
`batchFlushInterval`	number	`5000`	Συχνότητα αποστολής ομαδοποιημένων συμβάντων στον διακομιστή (χιλιοστά του δευτερολέπτου). Τα συμβάντα τοποθετούνται τοπικά σε ουρά και αποστέλλονται κάθε 5 δευτερόλεπτα, για λιγότερα αιτήματα δικτύου.
`batchSize`	number	`50`	Μέγιστος αριθμός συμβάντων στην ουρά πριν από την αυτόματη αποστολή. Αν συσσωρευτούν 50 πριν από τον χρονοδιακόπτη, αποστέλλονται αμέσως για αποφυγή απώλειας δεδομένων.
`sendImmediately`	boolean	`false`	Στέλνει κάθε συμβάν αμέσως χωρίς ομαδοποίηση (δεν συνιστάται για παραγωγή)
`sessionTimeout`	number	`1800000`	Λήξη συνεδρίας σε χιλιοστά του δευτερολέπτου (προεπιλογή: 30 λεπτά). Νέα συνεδρία ξεκινά μετά από αυτό το διάστημα αδράνειας.
`trackSessionStart`	boolean	`true`	Παρακολουθεί αυτόματα το συμβάν «Session Start» όταν ξεκινά νέα συνεδρία.
`trackPageViews`	boolean	`false`	Παρακολουθεί αυτόματα το «Page Viewed» κατά τη φόρτωση της σελίδας
`captureUTM`	boolean	`true`	Καταγράφει αυτόματα παραμέτρους UTM από το URL για απόδοση καμπάνιας
`resetSessionOnNewCampaign`	boolean	`false`	Ξεκινά νέα συνεδρία όταν αλλάζουν οι παράμετροι UTM (χρήσιμο για ανάλυση συνεδριών ανά καμπάνια)
`trackDeviceProperties`	boolean	`true`	Συμπεριλαμβάνει πληροφορίες συσκευής στο Session Start
`persistQueue`	boolean	`true`	Διατηρεί συμβάντα στην ουρά στο localStorage ώστε να επιβιώνουν από ανανέωση σελίδας
`inApp.allowHtmlJsInAppMessages`	boolean	`false`	Επιτρέπει in-app μηνύματα HTML, τα οποία εκτελούν JavaScript γραμμένη από τον συντάκτη σε sandboxed iframe στη σελίδα σας. Τα native μηνύματα εμφανίζονται ούτως ή άλλως. Δείτε Μηνύματα εντός εφαρμογής.

Ομαδοποίηση και αποστολή συμβάντων

Τα συμβάντα ομαδοποιούνται τοπικά και αποστέλλονται στον διακομιστή σε ομάδες για βέλτιστη χρήση δικτύου:

Αυτόματη αποστολή: τα συμβάντα στέλνονται κάθε batchFlushInterval χιλιοστά του δευτερολέπτου (προεπιλογή 5 δευτ.)
Αποστολή βάσει μεγέθους: αποστέλλονται αμέσως όταν συσσωρευτούν batchSize συμβάντα (προεπιλογή 50)
Μη αυτόματη αποστολή: καλέστε joryio.flush() για άμεση αποστολή των συμβάντων της ουράς
Κατά την έξοδο από τη σελίδα: τα συμβάντα αποστέλλονται αυτόματα με sendBeacon όταν ο χρήστης φεύγει από τη σελίδα
Όριο ουράς: η τοπική ουρά περιέχει έως 1.000 συμβάντα. Αν ξεπεραστεί το όριο (π.χ. σε μεγάλη περίοδο εκτός σύνδεσης), τα παλαιότερα συμβάντα απορρίπτονται με προειδοποίηση στην κονσόλα

// Send events immediately instead of batching
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sendImmediately: true  // Send each event immediately
});

// Or configure batching behavior
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  batchFlushInterval: 10000,  // Flush every 10 seconds
  batchSize: 20  // Or when 20 events accumulate
});

// Or manually flush at any time
joryio.track('Important Event', {...});
joryio.flush(); // Send now

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

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

Λήξη συνεδρίας: προεπιλογή 30 λεπτά αδράνειας (ρυθμίζεται μέσω sessionTimeout)
Νέα συνεδρία ξεκινά όταν:
1. Ο χρήστης φορτώνει τη σελίδα για πρώτη φορά
2. Παρέρχεται το χρονικό όριο συνεδρίας χωρίς συμβάντα
3. Ο χρήστης καλεί joryio.reset() (π.χ. κατά την αποσύνδεση)
4. Εντοπίζεται νέα καμπάνια (αν είναι ενεργοποιημένο το resetSessionOnNewCampaign)

Ρύθμιση λήξης συνεδρίας:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 3600000  // 1 hour in milliseconds
});

// Or shorter session timeout
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 600000  // 10 minutes
});

συμβουλή

Οι συνεδρίες διαχειρίζονται αυτόματα με βάση τη δραστηριότητα του χρήστη. Κάθε συμβάν που παρακολουθείται επαναφέρει τον χρονοδιακόπτη αδράνειας.

Παρακολούθηση έναρξης συνεδρίας

Από προεπιλογή, το SDK παρακολουθεί αυτόματα ένα συμβάν «Session Start» κάθε φορά που ξεκινά μια νέα συνεδρία. Αυτό το συμβάν:

Μπορεί να χρησιμοποιηθεί ως έναυσμα σε καμπάνιες και ροές journey
Περιλαμβάνει όλο το πλαίσιο συνεδρίας (παραμέτρους UTM, referrer, σελίδα προορισμού και - όταν είναι ενεργό το trackDeviceProperties - δεδομένα συσκευής)
Αποθηκεύεται στο προφίλ του χρήστη όπως κάθε άλλο συμβάν, ώστε τα τμήματα και τα analytics να μπορούν να μετρούν συνεδρίες ανά χρήστη

Παράδειγμα συμβάντος έναρξης συνεδρίας:

// Automatically tracked when user visits your site
{
  event: "Session Start",
  properties: {
    utm_source: "google",       // If UTM parameters present
    utm_medium: "cpc",
    utm_campaign: "spring_sale",
    referrer: "https://google.com",
    landing_page: "https://example.com/..."
  },
  userId: "user_123",           // If identified
  anonymousId: "anon_456",
  sessionId: "sess_789"
}

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

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

$user_agent
$timezone
$screen_width / $screen_height
$viewport_width / $viewport_height
$language / $languages
$platform
$browser
$device_id
country (ISO-3166-1 alpha-2, προέρχεται από IP κατά την έναρξη συνεδρίας)

Περιπτώσεις χρήσης:

Journeys καλωσορίσματος: χρησιμοποιήστε το Session Start ως έναυσμα journey για να προσεγγίσετε χρήστες όταν φτάνουν στον ιστότοπό σας.
Τμήματα βάσει συνεδρίας: τα συμβάντα Session Start αποθηκεύονται ανά χρήστη, ώστε οι συνθήκες τμημάτων βάσει συμβάντων να μπορούν να τα μετρούν - για παράδειγμα, «εκτέλεσε Session Start τουλάχιστον 10 φορές» (ενεργοί προχωρημένοι χρήστες) ή «δεν εκτέλεσε Session Start τις τελευταίες 7 ημέρες» (επανενεργοποίηση).
Απόδοση καμπάνιας: φιλτράρετε τα analytics στο Session Start και ομαδοποιήστε κατά utm_campaign για να δείτε ποιες καμπάνιες φέρνουν τις περισσότερες συνεδρίες.

Απενεργοποίηση παρακολούθησης έναρξης συνεδρίας:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  trackSessionStart: false  // Disable automatic session start events
});

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

Το 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 - το οποίο περιλαμβάνεται σε κάθε εφαρμογή και σελίδα - θα μπορούσε να αναφέρει εμφανίσεις και κλικ για μια καμπάνια που δεν εμφανίστηκε ποτέ, και τα δεδομένα σας θα τα μετρούσαν.

Οι ιστότοποι που φορτώνουν το φιλοξενούμενο bundle από το /sdk/web/latest/joryio.min.js το λαμβάνουν αυτόματα.

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

Περιεχόμενο	Τι είναι	Πώς αποδίδεται
Native	Δομημένα δεδομένα - τίτλος, κείμενο, εικόνα, κουμπιά	Απλά στοιχεία DOM, εισαγόμενα ως κόμβοι κειμένου. Χωρίς iframe, χωρίς εκτέλεση script.
HTML	Κώδικας HTML, CSS και JavaScript γραμμένος από τον συντάκτη	Ένα sandboxed iframe στη σελίδα σας.

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

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

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    allowHtmlJsInAppMessages: true,   // προεπιλογή: false
  },
});

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

Αν το Content Security Policy σας απαγορεύει inline scripts ή περιεχόμενο σε iframe, αφήστε το απενεργοποιημένο και συντάξτε τις καμπάνιες σας ως native μηνύματα.

Στυλ σε native μηνύματα από το δικό σας CSS

Ένα native μήνυμα είναι πραγματικό DOM στη σελίδα σας, όχι iframe, οπότε μπορείτε να το μορφοποιήσετε όπως οτιδήποτε δικό σας. Ο renderer εκθέτει σταθερά άγκιστρα:

.joryio-inapp-native                     /* η κάρτα */
.joryio-inapp-native h2                  /* τίτλος */
.joryio-inapp-native p                   /* σώμα */
.joryio-inapp-native img                 /* εικόνα */
.joryio-inapp-native button.primary      /* πρώτο κουμπί */
.joryio-inapp-native button.secondary    /* τα υπόλοιπα */
.joryio-inapp-close                      /* κλείσιμο */
.joryio-inapp-backdrop                   /* σκίαση */
.joryio-inapp-modal / -banner / -slideup / -fullscreen   /* ανά τύπο */

Προτιμήστε τις μεταβλητές από τους επιλογείς. Ό,τι μπορεί να ορίσει μια καμπάνια διαβάζεται από custom property, οπότε ορίζοντάς τες στο :root έχετε ένα στυλ σπιτιού που η καμπάνια μπορεί ακόμη να παρακάμψει για ένα μήνυμα:

:root {
  --joryio-inapp-bg: #0A1240;
  --joryio-inapp-fg: #FFFFFF;
  --joryio-inapp-primary: #00C8B7;
  --joryio-inapp-primary-fg: #041028;
  --joryio-inapp-radius: 18px;
  --joryio-inapp-font: 'Inter', system-ui, sans-serif;
  --joryio-inapp-size: 15px;
  --joryio-inapp-align: start;      /* start | center | end */
  --joryio-inapp-title-weight: 700;
}

Η προτεραιότητα, από την υψηλότερη:

όσα ορίζει η καμπάνια στο Style (optional) - γράφονται inline στην κάρτα
οι δικές σας τιμές --joryio-inapp-*
οι προεπιλογές του SDK, που είναι χρώματα συστήματος

Έτσι μια καμπάνια που δεν ορίζει τίποτα κληρονομεί το στυλ σας, ενώ μία που ορίζει φόντο υπερισχύει μόνο για εκείνο το μήνυμα. Χωρίς !important πουθενά.

Αν πάλι χρησιμοποιήσετε τους επιλογείς, το φύλλο στυλ του SDK εισάγεται τη στιγμή της εμφάνισης και άρα βρίσκεται μετά το δικό σας, οπότε κερδίζει στις ισοπαλίες. Προσθέστε ειδικότητα - .joryio-inapp .joryio-inapp-native {…} - αντί για έναν κανόνα μίας κλάσης.

Η κατεύθυνση ρυθμίζεται αυτόματα: η κάρτα φέρει dir="auto", οπότε ένα εβραϊκό ή αραβικό μήνυμα στοιχίζεται δεξιά μέσα σε μια κατά τα άλλα αριστερόστροφη σελίδα.

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

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

Callbacks

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    onMessageDisplay: (message) => console.log('shown', message.id),
    onMessageClick: (message, action) => console.log('clicked', action),
    onMessageDismiss: (message) => console.log('dismissed', message.id),
  },
});

Αναφορά API

Αρχικοποίηση

const joryio = new JoryioSDK(config)

Αρχικοποιήστε το SDK με τις ρυθμίσεις σας. Ο constructor επιστρέφει singleton - αν το κατασκευάσετε δεύτερη φορά, επιστρέφεται το υπάρχον instance.

Identify

joryio.identify(userId)

Συνδέει ένα αναγνωριστικό χρήστη με την τρέχουσα συνεδρία.

Παράμετροι:

userId (string): Μοναδικό αναγνωριστικό του χρήστη

Παράδειγμα:

joryio.identify('user_123');
joryio.setAttributes({
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});

Track

joryio.track(eventName, properties?)

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

Παράμετροι:

eventName (string): Όνομα του συμβάντος
properties (object, προαιρετικό): Ιδιότητες συμβάντος

Παράδειγμα:

joryio.track('Order Completed', {
  order_id: 'order_789',
  total: 149.99,
  items: 3,
});

Παρακολούθηση προβολών σελίδας

Ενεργοποιήστε την αυτόματη παρακολούθηση προβολών σελίδας:

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

Alias

joryio.alias(newUserId)

Συνδέστε έναν ανώνυμο χρήστη με ένα γνωστό αναγνωριστικό χρήστη (χρήσιμο μετά την εγγραφή).

Παράμετροι:

newUserId (string): Το νέο αναγνωριστικό χρήστη που θα συσχετιστεί

Παράδειγμα:

// Before signup (anonymous tracking)
joryio.track('Viewed Landing Page');

// After signup
joryio.alias('user_123');
joryio.identify('user_123');
joryio.setAttributes({ email: 'user@example.com' });

Προσθήκη alias

joryio.addAlias(aliasLabel, aliasName)

Προσθέστε ένα alias με ετικέτα στον τρέχοντα αναγνωρισμένο χρήστη.

Παράδειγμα:

joryio.addAlias('crm', 'crm_98765');

Reset

joryio.reset()

Εκκαθαρίζει την τρέχουσα συνεδρία χρήστη (χρήσιμο κατά την αποσύνδεση). Εκκαθαρίζει επίσης όλα τα δεδομένα UTM, συμπεριλαμβανομένης της απόδοσης πρώτης και τελευταίας επαφής.

Παράδειγμα:

// On user logout
function handleLogout() {
  joryio.reset();
  // ... other logout logic
}

Λήψη ανώνυμου ID

joryio.getAnonymousId()

Επιστρέφει το τρέχον ανώνυμο ID - το ID που η Joryio αναθέτει σε κάθε επισκέπτη πριν ταυτοποιηθεί. Δημιουργείται κατά την πρώτη αρχικοποίηση, αποθηκεύεται στο localStorage και παραμένει σταθερό σε όλες τις φορτώσεις σελίδων για όλη τη διάρκεια ζωής του ανώνυμου επισκέπτη (το reset() το αναδημιουργεί κατά την αποσύνδεση). Είναι ακριβώς το anonymousId που επισυνάπτεται σε κάθε συμβάν που στέλνει το track(), οπότε χρησιμοποιήστε το για να συνδέσετε ένα συμβάν από την πλευρά του διακομιστή ή μια εγγραφή συγκατάθεσης με το ίδιο προφίλ.

Επιστρέφει:

string - το ανώνυμο ID (πάντα παρόν)

Διαβάστε το αφού φορτωθεί το SDK

Με το ασύγχρονο snippet, το window.joryio είναι μια ουρά εντολών μέχρι να ολοκληρωθεί η φόρτωση του SDK, και μια εντολή στην ουρά δεν μπορεί να επιστρέψει τιμή. Διαβάστε το ID στο επιλυμένο στιγμιότυπο μετά τη φόρτωση, ή μέσα από το ready() (παρακάτω).

Παράδειγμα:

joryio.ready(function (sdk) {
  const anonId = sdk.getAnonymousId();
  fetch('/consent', { method: 'POST', body: JSON.stringify({ anonymousId: anonId }) });
});

Λήψη ID χρήστη

joryio.getUserId()

Επιστρέφει το τρέχον ID ταυτοποιημένου χρήστη, ή null αν ο επισκέπτης είναι ακόμη ανώνυμος (δηλαδή δεν έχει κληθεί το identify()).

Επιστρέφει:

string | null

Παράδειγμα:

joryio.ready(function (sdk) {
  const userId = sdk.getUserId(); // null μέχρι να καλέσετε το joryio.identify(...)
});

Ready

joryio.ready(callback)

Εκτελεί το callback(sdk) αφού φορτωθεί και αρχικοποιηθεί το SDK. Αυτός είναι ο ασφαλής τρόπος για να διαβάσετε μια τιμή (όπως getAnonymousId() / getUserId()) που ένα stub στην ουρά δεν μπορεί να επιστρέψει πριν τη φόρτωση. Το callback λαμβάνει το στιγμιότυπο του SDK· αν το SDK έχει ήδη φορτωθεί, εκτελείται αμέσως.

Παράδειγμα:

joryio.ready(function (sdk) {
  console.log('anon:', sdk.getAnonymousId(), 'user:', sdk.getUserId());
});

Λήψη δεδομένων UTM

joryio.getUTMData()

Επιστρέφει τις τρέχουσες παραμέτρους UTM, καθώς και εκείνες της πρώτης και της τελευταίας επαφής.

Επιστρέφει:

Ένα αντικείμενο με δεδομένα UTM current, firstTouch και lastTouch

Παράδειγμα:

const utmData = joryio.getUTMData();
console.log(utmData.current?.utm_source); // "google"
console.log(utmData.firstTouch?.utm_campaign); // "awareness_campaign"
console.log(utmData.lastTouch?.utm_campaign); // "conversion_campaign"

Ενημέρωση UTM

joryio.updateUTM()

Ενημερώστε μη αυτόματα τις παραμέτρους UTM από το τρέχον URL. Χρήσιμο για Single Page Applications που αλλάζουν URL χωρίς ανανέωση της σελίδας.

Παράδειγμα:

// React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    joryio.updateUTM();
  }, [location]);
}

// Vue Router
router.afterEach(() => {
  joryio.updateUTM();
});

Γνωρίσματα πίνακα

joryio.addToArray(key, value)
joryio.removeFromArray(key, value)

Χειριστείτε αποτελεσματικά γνωρίσματα τύπου πίνακα.

Παράμετροι:

key (string): Όνομα γνωρίσματος
value (any): Τιμή προς προσθήκη ή αφαίρεση

Παράδειγμα:

// Add tags to user
joryio.addToArray('tags', 'vip');
joryio.addToArray('tags', 'premium');
// Result: tags = ['vip', 'premium']

// Add duplicate (no-op, prevents duplicates)
joryio.addToArray('tags', 'vip');
// Result: tags = ['vip', 'premium'] (unchanged)

// Remove tag
joryio.removeFromArray('tags', 'vip');
// Result: tags = ['premium']

// Common use cases
joryio.addToArray('interests', 'technology');
joryio.addToArray('purchasedProducts', 'prod_123');
joryio.addToArray('featureFlags', 'beta-access');

Συμπεριφορά:

Το addToArray() προσθέτει την τιμή μόνο αν δεν υπάρχει ήδη (αποτρέπει διπλότυπα)
Το addToArray() δημιουργεί νέο πίνακα αν το γνώρισμα δεν υπάρχει
Το removeFromArray() αφαιρεί όλες τις εμφανίσεις της τιμής
Οι αλλαγές συγχρονίζονται αυτόματα με το backend, τόσο για αναγνωρισμένους όσο και για ανώνυμους χρήστες

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

Το Web SDK εμπλουτίζει αυτόματα τα συμβάντα Session Start με δεδομένα συσκευής και περιβάλλοντος. Αυτές οι τιμές αποθηκεύονται στο προφίλ χρήστη και στις εγγραφές συσκευής:

$user_agent
$timezone
$screen_width / $screen_height
$viewport_width / $viewport_height
$language / $languages
$platform
$browser
$device_id
country (ISO-3166-1 alpha-2, προέρχεται από IP κατά την έναρξη συνεδρίας)

Ιδιότητες συμβάντων

Τυπικές ιδιότητες

Κάθε αποθηκευμένο συμβάν περιέχει αυτές τις ιδιότητες - το $device_id προστίθεται από το SDK και οι υπόλοιπες προστίθενται από το pipeline εισαγωγής του Joryio όταν λαμβάνεται το συμβάν:

$device_id: Σταθερό αναγνωριστικό συσκευής ανά πρόγραμμα περιήγησης (προστίθεται από το SDK)
$session_id: Αναγνωριστικό τρέχουσας συνεδρίας
$anonymous_id: Αναγνωριστικό ανώνυμου χρήστη (πριν από την αναγνώριση)
$app_id: Αναγνωριστικό εφαρμογής σας
$app_name: Όνομα εφαρμογής σας
$platform: Πάντα web για το Web SDK
$is_identified: Αν ο χρήστης έχει αναγνωριστεί

Το πρόθεμα $ είναι δεσμευμένο - μην το χρησιμοποιείτε για δικές σας ιδιότητες.

Προσαρμοσμένες ιδιότητες

Μπορείτε να προσθέσετε οποιεσδήποτε προσαρμοσμένες ιδιότητες στα συμβάντα σας:

joryio.track('Video Played', {
  video_id: 'vid_123',
  video_title: 'Product Demo',
  duration: 120,
  autoplay: false,
  // Any other custom data
});

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

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

Αρχικοποιήστε το SDK όσο το δυνατόν νωρίτερα στην εφαρμογή σας:

// In your main app file
import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({
  sdkKey: process.env.JORYIO_SDK_KEY,
  enableDebug: process.env.NODE_ENV === 'development',
});

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

Εστιάστε στην παρακολούθηση συμβάντων που είναι σημαντικά για την επιχείρησή σας:

// Good: Specific, actionable events
joryio.track('Trial Started', { plan: 'premium' });
joryio.track('Feature Used', { feature: 'export', format: 'csv' });

// Avoid: Overly generic events
joryio.track('Button Clicked'); // Too generic

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

Χρησιμοποιήστε μια συνεπή σύμβαση ονοματοδοσίας για συμβάντα και ιδιότητες:

// Good: Clear, consistent naming
joryio.track('Subscription Upgraded', {
  from_plan: 'basic',
  to_plan: 'premium',
  billing_cycle: 'monthly',
});

// Avoid: Inconsistent naming
joryio.track('upgraded_subscription', {
  FromPlan: 'basic',
  'to-plan': 'premium',
});

4. Χειριστείτε τον κύκλο ζωής χρήστη

Χειριστείτε σωστά την αναγνώριση χρήστη και τη διαχείριση συνεδριών:

// On login
function handleLogin(userId, userInfo) {
  joryio.identify(userId);
  joryio.setAttributes({
    email: userInfo.email,
    name: userInfo.name,
  });
}

// On logout
function handleLogout() {
  joryio.reset();
}

// On signup
function handleSignup(userId, userInfo) {
  joryio.alias(userId);
  joryio.identify(userId);
  joryio.setAttributes(userInfo);
}

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

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

Ελέγξτε το κλειδί SDK - βεβαιωθείτε ότι ξεκινά με jry_sdk_web_
Ελέγξτε την κονσόλα - ενεργοποιήστε τη λειτουργία εντοπισμού σφαλμάτων για λεπτομερή logs
Επαληθεύστε την αρχικοποίηση - βεβαιωθείτε ότι το new JoryioSDK(config) εκτελείται πριν κληθούν άλλες μέθοδοι

Σφάλματα CORS

Τα endpoints παρακολούθησης του SDK απαντούν με Access-Control-Allow-Origin: *, επομένως δεν απαιτείται επιτρεπόμενη λίστα domain. Αν εξακολουθείτε να βλέπετε σφάλματα CORS, ελέγξτε ότι το apiEndpoint δείχνει στο σωστό βασικό URL (https://api-eu1.joryio.com) και ότι το αίτημα δεν αποκλείεται από επέκταση προγράμματος περιήγησης ή proxy που αφαιρεί κεφαλίδες CORS.

Προβλήματα παρακολούθησης συνεδρίας

Το SDK χρησιμοποιεί localStorage για διατήρηση συνεδρίας. Βεβαιωθείτε ότι:

Ο ιστότοπός σας σερβίρεται μέσω HTTPS (απαιτείται για ασφαλή contexts)
Οι χρήστες δεν έχουν απενεργοποιήσει το localStorage
Δεν καλείτε κατά λάθος το reset()

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

Web SDK: UTM & Attribution - Απόδοση καμπάνιας, πρώτη/τελευταία επαφή και καταγραφή UTM
E-Commerce Tracking - Συμβάντα προϊόντων, καλαθιού, checkout και παραγγελιών
Παρακολούθηση προσαρμοσμένων συμβάντων
Ορισμός γνωρισμάτων χρήστη
Δημιουργία τμημάτων
Δημιουργία καμπανιών

Εγκατάσταση​

Μέσω npm/yarn​

Μέσω CDN​

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

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

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

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

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

Ομαδοποίηση και αποστολή συμβάντων​

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

Παρακολούθηση έναρξης συνεδρίας​

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

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

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

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

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

Στυλ σε native μηνύματα από το δικό σας CSS​

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

Callbacks​

Αναφορά API​

Αρχικοποίηση​

Identify​

Track​

Alias​

Προσθήκη alias​

Reset​

Λήψη ανώνυμου ID​

Λήψη ID χρήστη​

Ready​

Λήψη δεδομένων UTM​

Ενημέρωση UTM​

Γνωρίσματα πίνακα​

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

Ιδιότητες συμβάντων​

Τυπικές ιδιότητες​

Προσαρμοσμένες ιδιότητες​

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

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

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

3. Χρησιμοποιήστε συνεπή ονοματοδοσία​

4. Χειριστείτε τον κύκλο ζωής χρήστη​

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

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

Σφάλματα CORS​

Προβλήματα παρακολούθησης συνεδρίας​

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

Εγκατάσταση

Μέσω npm/yarn

Μέσω CDN

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

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

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

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

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

Ομαδοποίηση και αποστολή συμβάντων

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

Παρακολούθηση έναρξης συνεδρίας

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

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

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

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

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

Στυλ σε native μηνύματα από το δικό σας CSS

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

Callbacks

Αναφορά API

Αρχικοποίηση

Identify

Track

Alias

Προσθήκη alias

Reset

Λήψη ανώνυμου ID

Λήψη ID χρήστη

Ready

Λήψη δεδομένων UTM

Ενημέρωση UTM

Γνωρίσματα πίνακα

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

Ιδιότητες συμβάντων

Τυπικές ιδιότητες

Προσαρμοσμένες ιδιότητες

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

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

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

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

4. Χειριστείτε τον κύκλο ζωής χρήστη

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

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

Σφάλματα CORS

Προβλήματα παρακολούθησης συνεδρίας

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