Προσαρμοσμένα γνωρίσματα χρηστών

Τα γνωρίσματα χρηστών είναι ιδιότητες που περιγράφουν τους χρήστες σας. Χρησιμοποιήστε τα για να εξατομικεύσετε μηνύματα, να δημιουργήσετε τμήματα και να αναλύσετε τη βάση χρηστών σας.

Τι είναι τα γνωρίσματα χρηστών;

Τα γνωρίσματα είναι ζεύγη κλειδιού-τιμής που συνδέονται με προφίλ χρηστών:

{
  "userId": "user_123",
  "email": "[email protected]",
  "attributes": {
    "firstName": "John",
    "lastName": "Doe",
    "plan": "premium",
    "signupDate": "2024-01-15",
    "totalPurchases": 5,
    "lastLoginDate": "2024-01-20",
    "preferences": {
      "newsletter": true,
      "notifications": "email"
    }
  }
}

Ορισμός γνωρισμάτων

Μέσω SDK (πλευρά πελάτη)

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

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

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

// Set attributes separately
joryio.setAttributes({
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe',
  plan: 'premium',
  signupDate: '2024-01-15'
});

// Update attributes later
joryio.setAttributes({
  plan: 'enterprise',
  lastUpgrade: new Date().toISOString()
});

Μέσω API (πλευρά διακομιστή)

// Create or update user with attributes
fetch('https://api-eu1.joryio.com/api/users/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer jry_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      externalId: 'user_123',
      email: '[email protected]',
      attributes: {
        firstName: 'John',
        plan: 'premium',
        totalOrders: 10,
        lifetimeValue: 1250.00
      }
    }
  })
});

Τυπικά έναντι προσαρμοσμένων γνωρισμάτων

Τυπικά γνωρίσματα

Στείλτε τους αριθμούς τηλεφώνου με + και κωδικό χώρας

Στέλνετε πάντα τους αριθμούς τηλεφώνου σε πλήρη διεθνή μορφή (E.164): +, ο κωδικός χώρας και μετά ο αριθμός - για παράδειγμα +972501234567. Ένας αριθμός χωρίς + διαβάζεται με την προεπιλεγμένη χώρα για αριθμούς τηλεφώνου του χώρου εργασίας· αν δεν έχει οριστεί, ή αν τα ψηφία διαβάζονται με δύο τρόπους, αποθηκεύεται ως μη επαληθευμένος και δεν χρησιμοποιείται για μηνύματα. Πώς χειρίζονται οι αριθμοί τηλεφώνου

Δεσμεύονται από το Joryio (αποθηκεύονται στο ριζικό επίπεδο):

• userId - Μοναδικό αναγνωριστικό χρήστη
• email - Διεύθυνση email
• phone - Αριθμός τηλεφώνου
• externalId - ID εξωτερικού συστήματος
• createdAt - Χρονική σήμανση δημιουργίας χρήστη
• updatedAt - Χρονική σήμανση τελευταίας ενημέρωσης

Προσαρμοσμένα γνωρίσματα

Οποιεσδήποτε άλλες ιδιότητες ορίζετε (αποθηκεύονται στο αντικείμενο attributes):

• firstName, lastName, name
• plan, subscription Tier
• company, industry, jobTitle
• totalPurchases, lifetimeValue
• preferences, settings
• Και οτιδήποτε άλλο χρειάζεστε!

Τύποι δεδομένων

Τα γνωρίσματα υποστηρίζουν πολλούς τύπους δεδομένων:

Κείμενο

{
  firstName: "John",
  plan: "premium",
  country: "US"
}

Αριθμός

{
  age: 30,
  totalPurchases: 15,
  lifetimeValue: 1250.50
}

Λογική τιμή

{
  emailVerified: true,
  newsletter: false,
  isPremium: true
}

Ημερομηνία/χρονική σήμανση

{
  signupDate: "2024-01-15",
  lastLoginDate: "2024-01-20T10:30:00Z",
  trialEndsAt: "2024-02-15T23:59:59Z"
}

Χρησιμοποιήστε μορφή ISO 8601

Για ημερομηνίες, χρησιμοποιήστε τη μορφή ISO 8601: YYYY-MM-DDTHH:mm:ssZ

Πίνακας

{
  tags: ["vip", "early-adopter"],
  interests: ["technology", "sports", "music"],
  purchasedProducts: ["product_1", "product_2"]
}

Αντικείμενο/ένθετο

{
  preferences: {
    theme: "dark",
    language: "en",
    notifications: {
      email: true,
      sms: false,
      push: true
    }
  },
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip: "94102"
  }
}

Πώς καθορίζεται ένας τύπος

Το Joryio δεν μαντεύει ποτέ από το ΟΝΟΜΑ ενός πεδίου. Ο τύπος καθορίζεται με αυτή τη σειρά:

1. Δηλωμένος - κάποιος όρισε τον τύπο στη σελίδα Χαρακτηριστικά (ή στη σελίδα Συμβάντα, για ιδιότητες συμβάντων). Αυτό υπερισχύει πάντα.
2. Τυπικό πεδίο εμπορίου - τα price, total, revenue, quantity, tax, shipping, discount, subtotal και value αντιμετωπίζονται ως αριθμοί από προεπιλογή, είτε στέλνετε 12.34 είτε "12.34". Αναγνωριστικά όπως order_id και sku δεν περιλαμβάνονται σκόπιμα: συχνά μοιάζουν αριθμητικά, και το να τα ορίσετε ως αριθμούς είναι ο λόγος που μια παραγγελία 007 σταματά να ταιριάζει.
3. Συναγόμενος από τα δεδομένα σας - ο συχνότερος τύπος σε ένα δείγμα, ανά συμβάν. Τα Product Added.step και Onboarding Step Tapped.step τυποποιούνται ξεχωριστά.

Όταν οι τιμές διαφωνούν

Αν πάνω από ~20% των τιμών είναι διαφορετικού τύπου, το χαρακτηριστικό εμφανίζεται ως Μικτό με τα πλήθη (π.χ. string 994 - number 448). Το Joryio δεν επιλέγει πλευρά: συγκρίνει ως κείμενο - που δεν δίνει ποτέ λάθος απάντηση, μόνο χονδρική - και σας ζητά να ορίσετε τον τύπο.

Ο ορισμός του τύπου διορθώνει τη σύγκριση και για ήδη αποθηκευμένες τιμές: ένα πεδίο δηλωμένο ως αριθμός συγκρίνει το "12.34" και το 12.34 ως τον ίδιο αριθμό, οπότε το price > 100 παύει να συγκρίνει κείμενο (όπου "90" > "100" είναι αληθές).

σημείωση

Η δήλωση τύπου αλλάζει τον τρόπο ΣΥΓΚΡΙΣΗΣ των τιμών. Δεν ξαναγράφει ό,τι αποθηκεύτηκε - τα ιστορικά σας δεδομένα διατηρούν ακριβώς τις τιμές που στείλατε.

Τι κοστίζει ο ορισμός ενός τύπου

Ο ορισμός τύπου είναι απόφαση για το πώς θα αντιμετωπιστεί μια διαφωνία, όχι τρόπος να τερματιστεί. Οι τιμές που δεν μπορούν να διαβαστούν ως ο τύπος που επιλέξατε παύουν να ταιριάζουν σε φίλτρα - και βγαίνουν εκτός και από τις δύο πλευρές ενός εύρους.

Έστω ότι το step έχει τους αριθμούς 1, 2, 3 στα περισσότερα συμβάντα και τις λέξεις "invite" και "photo" σε λίγα, και το ορίζετε ως Αριθμό:

φίλτρο	επαφή με step "invite"
step > 1	δεν ταιριάζει
step <= 1	δεν ταιριάζει
step = 1	δεν ταιριάζει
step δεν είναι 1	ταιριάζει
το step υπάρχει	ταιριάζει

Έτσι δύο τμήματα που προορίζονταν να χωρίσουν το κοινό στα δύο - step > 1 και step <= 1 - αφήνουν αυτές τις επαφές σε κανένα. Ένα split test φτιαγμένο έτσι τις χάνει σιωπηλά.

Οι αριθμοί γραμμένοι ως κείμενο είναι εντάξει: το "12.34" διαβάζεται ως 12.34 και ταιριάζει κανονικά. Επηρεάζονται μόνο οι τιμές χωρίς ανάγνωση ως ο επιλεγμένος τύπος.

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

Τα τυπικά πεδία τυποποιούνται για εσάς

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

• Χαρακτηριστικά πλατφόρμας που γράφει το σύστημα - lastEventTime (μια ημερομηνία, αν και αποθηκεύεται ως κείμενο), total_purchases, ml_churn_score, is_purchase_overdue.
• Τυπικές ιδιότητες εμπορίου - price, total, revenue, quantity, tax, shipping, discount, subtotal, value.

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

Αν κάποιο από αυτά τα ονόματα σημαίνει κάτι άλλο στα δεδομένα σας, στείλτε το με άλλο όνομα. Ένα price που είναι στην ουσία ετικέτα πρέπει να είναι price_label. Ό,τι είναι εκτός αυτών των λιστών το ορίζετε εσείς.

Συνήθη παραδείγματα γνωρισμάτων

E-commerce

joryio.setAttributes({
  // Account info
  accountType: "premium",
  memberSince: "2024-01-15",

  // Purchase history
  totalOrders: 15,
  lastOrderDate: "2024-01-20",
  lifetimeValue: 2500.00,
  avgOrderValue: 166.67,

  // Preferences
  favoriteCategory: "electronics",
  preferredShipping: "express",

  // Engagement
  cartAbandoned: false,
  wishlistItems: 5,
  reviewsWritten: 3
});

SaaS

joryio.setAttributes({
  // Subscription
  plan: "pro",
  billingCycle: "monthly",
  subscriptionStatus: "active",
  trialEndsAt: "2024-02-15T23:59:59Z",
  mrr: 99,

  // Usage
  loginCount: 45,
  lastLoginDate: "2024-01-20",
  featuresUsed: ["export", "api", "integrations"],
  apiCallsThisMonth: 10500,
  storageUsedGB: 15.5,

  // Team
  teamSize: 8,
  role: "admin",
  companyName: "Acme Corp"
});

Πολυμέσα/περιεχόμενο

joryio.setAttributes({
  // Subscription
  subscriptionTier: "premium",
  contentAccessLevel: "unlimited",

  // Engagement
  articlesRead: 125,
  videosWatched: 45,
  podcastsListened: 30,
  favoriteTopics: ["technology", "business"],

  // Behavior
  avgSessionDuration: 25.5,
  lastVisit: "2024-01-20T14:30:00Z",
  deviceType: "mobile"
});

Ενημέρωση γνωρισμάτων

Συγχώνευση έναντι αντικατάστασης

Συγχώνευση (προεπιλογή) - Ενημερώνει τα καθορισμένα πεδία:

// Initial attributes
{
  firstName: "John",
  plan: "free",
  country: "US"
}

// Update attributes (merges with existing)
joryio.setAttributes({
  plan: "premium"
});

// Result (plan updated, others preserved)
{
  firstName: "John",
  plan: "premium",  // Updated
  country: "US"      // Preserved
}

Τα γνωρίσματα συγχωνεύονται

Η κλήση setAttributes() συγχωνεύει νέα γνωρίσματα με τα υπάρχοντα. Τα υπάρχοντα γνωρίσματα που δεν αναφέρονται στην κλήση διατηρούνται.

Αύξηση/μείωση

Για μετρητές, αυξήστε αντί να ανακτήσετε την τρέχουσα τιμή:

// Bad: Race condition possible
const current = await getUserAttribute('loginCount');
joryio.setAttributes({ loginCount: current + 1 });

// Good: Atomic increment
joryio.incrementAttribute('loginCount', 1);

// Decrement
joryio.incrementAttribute('creditsRemaining', -10);

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

Μπορείτε να αποθηκεύετε και να χειρίζεστε πίνακες ως τιμές γνωρισμάτων:

// Set array attribute
joryio.setAttributes({
  tags: ['vip', 'early-adopter'],
  interests: ['technology', 'sports']
});

// Add to array (only adds if value doesn't already exist)
joryio.addToArray('tags', 'premium');
// Result: ['vip', 'early-adopter', 'premium']

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

// Remove from array
joryio.removeFromArray('tags', 'early-adopter');
// Result: ['vip', 'premium']

Λεπτομέρειες μεθόδων:

Μέθοδος	Περιγραφή
addToArray(key, value)	Προσθέτει τιμή στον πίνακα αν δεν υπάρχει ήδη (αποτρέπει διπλότυπα). Δημιουργεί νέο πίνακα αν το γνώρισμα δεν υπάρχει.
removeFromArray(key, value)	Αφαιρεί όλες τις εμφανίσεις της τιμής από τον πίνακα. Προειδοποιεί αν το γνώρισμα δεν είναι πίνακας.

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

Τα γνωρίσματα πίνακα είναι ιδανικά για:

• Ετικέτες χρηστών: ['vip', 'trial', 'beta-tester']
• Ενδιαφέροντα: ['sports', 'technology', 'fashion']
• Αγορασμένα προϊόντα: ['prod_123', 'prod_456']
• Σημαίες δυνατοτήτων: ['feature-a', 'feature-b']
• Ρόλους: ['admin', 'editor']

Χρήση γνωρισμάτων για τμηματοποίηση

Δημιουργήστε τμήματα βάσει γνωρισμάτων:

Απλό φίλτρο γνωρίσματος

plan equals "premium"

Αριθμητική σύγκριση

lifetimeValue >= 1000
totalPurchases > 5
age between 25 and 45

Φίλτρα βάσει ημερομηνίας

signupDate is within last 30 days
trialEndsAt is within next 7 days
lastLoginDate is more than 14 days ago

Αντιστοίχιση κειμένου

email contains "@company.com"
country equals "US"
firstName exists
plan is not "free"

Φίλτρα πίνακα

tags contains "vip"
interests contains any of ["technology", "business"]

Εξατομίκευση μηνυμάτων

Χρησιμοποιήστε γνωρίσματα στο περιεχόμενο καμπάνιας:

Εξατομίκευση email

Hi {{firstName}},

Your {{plan}} plan includes these benefits:
...

{{#if trialEndsAt}}
  Your trial ends on {{trialEndsAt}}. Upgrade now!
{{/if}}

Δυναμικό περιεχόμενο

{{#if plan == "free"}}
  <p>Upgrade to Premium for more features!</p>
{{else}}
  <p>Thanks for being a {{plan}} member!</p>
{{/if}}

Μπλοκ υπό συνθήκες

{{#if totalPurchases > 10}}
  <div class="vip-offer">
    As a valued customer, here's an exclusive offer...
  </div>
{{/if}}

Βέλτιστες πρακτικές γνωρισμάτων

1. Χρησιμοποιήστε περιγραφικά ονόματα

Καλό:

{
  subscriptionTier: "premium",
  lifetimeValueUSD: 1250.00,
  emailVerified: true
}

Κακό:

{
  sub: "p",
  ltv: 1250,
  verified: 1
}

2. Να είστε συνεπείς

Χρησιμοποιήστε την ίδια σύμβαση ονοματοδοσίας:

Καλό (camelCase):

{
  firstName: "John",
  lastName: "Doe",
  signupDate: "2024-01-15"
}

Κακό (μικτό):

{
  first_name: "John",
  LastName: "Doe",
  "signup-date": "2024-01-15"
}

3. Χρησιμοποιήστε κατάλληλους τύπους

Καλό:

{
  age: 30,                    // Number
  isPremium: true,            // Boolean
  signupDate: "2024-01-15",  // ISO Date String
  tags: ["vip", "beta"]      // Array
}

Κακό:

{
  age: "30",                  // String instead of number
  isPremium: "true",          // String instead of boolean
  signupDate: 1705276800,    // Timestamp instead of ISO
  tags: "vip,beta"           // String instead of array
}

4. Μην αποθηκεύετε ευαίσθητα δεδομένα

Μην αποθηκεύετε ποτέ:

• Κωδικούς ή hashes κωδικών
• Πλήρεις αριθμούς πιστωτικών καρτών
• Αριθμούς κοινωνικής ασφάλισης
• Τραπεζικά στοιχεία
• Πληροφορίες υγείας

Είναι ασφαλές να αποθηκεύετε:

• Τα τελευταία 4 ψηφία κάρτας
• Τύπο μεθόδου πληρωμής ("visa", "mastercard")
• Κρυπτογραφημένα/hashed tokens
• Δημόσιες πληροφορίες προφίλ

5. Διατηρήστε σύντομα τα ονόματα γνωρισμάτων

Καλό: plan, ltv, mrr Κακό: currentSubscriptionPlanTierLevel

Δεσμευμένα ονόματα γνωρισμάτων

Αποφύγετε τη χρήση αυτών των δεσμευμένων ονομάτων:

• userId, user_id, id
• email
• phone
• createdAt, created_at
• updatedAt, updated_at
• $app_id, $platform (με πρόθεμα $)

Μαζικές ενημερώσεις

Ενημερώστε γνωρίσματα για πολλούς χρήστες:

// API: Bulk update - each field of POST /users/track accepts an array (attributes: max 1000)
POST /users/track
{
  "attributes": [
    {
      "externalId": "user_1",
      "attributes": { "plan": "premium" }
    },
    {
      "externalId": "user_2",
      "attributes": { "plan": "enterprise" }
    }
  ]
}

Όρια γνωρισμάτων

Όριο	Τιμή
Μέγιστα γνωρίσματα ανά χρήστη	200
Μέγιστο μήκος ονόματος γνωρίσματος	100 χαρακτήρες
Μέγιστο μήκος τιμής κειμένου	10.000 χαρακτήρες
Μέγιστο μήκος πίνακα	100 στοιχεία
Μέγιστο βάθος ένθεσης	5 επίπεδα

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

Δεν εμφανίζονται γνωρίσματα

1. Ελέγξτε την ορθογραφία του ονόματος γνωρίσματος
2. Επαληθεύστε ότι ο χρήστης έχει αναγνωριστεί
3. Ενεργοποιήστε τη λειτουργία εντοπισμού για να δείτε κλήσεις API
4. Ελέγξτε για σφάλματα API στην απόκριση

Δεν ενημερώνεται γνώρισμα

1. Βεβαιωθείτε ότι χρησιμοποιείτε συγχώνευση (όχι αντικατάσταση)
2. Ελέγξτε ότι ο τύπος δεδομένων ταιριάζει
3. Επαληθεύστε ότι το όνομα γνωρίσματος είναι σωστό
4. Ελέγξτε τα όρια ρυθμού

Δεν λειτουργεί η τμηματοποίηση

1. Επαληθεύστε ότι το γνώρισμα υπάρχει για τους χρήστες
2. Ελέγξτε τον τύπο δεδομένων γνωρίσματος
3. Δοκιμάστε τη λογική φίλτρου με γνωστούς χρήστες
4. Βεβαιωθείτε ότι οι τιμές γνωρίσματος ταιριάζουν ακριβώς με το φίλτρο

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

• Καταγράψτε προσαρμοσμένα συμβάντα
• Δημιουργήστε τμήματα με γνωρίσματα
• Εξατομικεύστε καμπάνιες
• Αναφορά User API