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

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

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

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

{
  "userId": "user_123",
  "email": "john@example.com",
  "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: 'john@example.com',
  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/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer jry_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_123',
    email: 'john@example.com',
    attributes: {
      firstName: 'John',
      plan: 'premium',
      totalOrders: 10,
      lifetime Value: 1250.00
    }
  })
});

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

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

Δεσμεύονται από το 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"
  }
}

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

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 - POST /users accepts a bare array body (max 1000)
POST /users
[
  {
    "userId": "user_1",
    "attributes": { "plan": "premium" }
  },
  {
    "userId": "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