Ενσωμάτωση React Native SDK

React Native wrapper που γεφυρώνει τα εγγενή iOS και Android SDK, προσφέροντας πλήρεις δυνατότητες πλατφόρμας με ένα μόνο TypeScript API.

Δυνατότητες

• Native Bridge - Τυλίγει τα εγγενή iOS (Swift) και Android (Kotlin) SDK
• Παρακολούθηση συμβάντων - Παρακολούθηση προσαρμοσμένων συμβάντων και προβολών οθόνης
• Ταυτότητα χρήστη - Αναγνώριση, alias και διαχείριση γνωρισμάτων χρήστη
• Push Notifications - Καταχώριση tokens, παρακολούθηση clicks (FCM + APNs)
• Μηνύματα εντός εφαρμογής - Λήψη και εμφάνιση μηνυμάτων εντός εφαρμογής
• E-Commerce - Παρακολούθηση αγορών, συμβάντων καλαθιού και checkout
• Υποστήριξη εκτός σύνδεσης - Τα συμβάντα μπαίνουν τοπικά σε ουρά και συγχρονίζονται όταν υπάρχει σύνδεση
• Αυτόματη επανάληψη - Exponential backoff σε αποτυχίες δικτύου

Απαιτήσεις

• React Native 0.72+
• iOS 14.0+ / Android SDK 24+
• TypeScript 5.0+ (συνιστάται)

Εγκατάσταση

npm install @joryio/react-native-sdk

Ρύθμιση iOS

cd ios && pod install

Ρύθμιση Android

Προσθέστε το πακέτο Joryio στο MainApplication.kt:

import io.joryio.reactnative.JoryioPackage

override fun getPackages() = PackageList(this).packages.apply {
    add(JoryioPackage())
}

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

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

// Initialize once in App.tsx
await Joryio.initialize(
  'jry_sdk_ios_your_key',  // Your SDK key
  'api-eu1.joryio.com',    // API host (bare hostname, no scheme)
  {
    enableDebug: __DEV__,
    trackSessionStart: true,
  }
);

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

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

// Basic event
Joryio.track('Button Clicked');

// Event with properties
Joryio.track('Product Added', {
  productId: 'SKU-123',
  productName: 'Blue T-Shirt',
  price: 29.99,
  currency: 'USD',
});

// E-commerce events
Joryio.track('Checkout Started', {
  value: 89.97,
  items: [
    { productId: 'SKU-123', quantity: 2, price: 29.99 },
    { productId: 'SKU-456', quantity: 1, price: 29.99 },
  ],
});

Joryio.track('Order Completed', {
  order_id: 'ORD-789',
  value: 89.97,
  currency: 'USD',
});

Παρακολούθηση προβολών οθόνης

// In your screen components
Joryio.trackScreen('ProductDetail', { productId: 'SKU-123' });
Joryio.trackScreen('Cart');
Joryio.trackScreen('Checkout');

Ενσωμάτωση React Navigation

import { NavigationContainer } from '@react-navigation/native';

function App() {
  const routeNameRef = useRef<string>();

  return (
    <NavigationContainer
      onStateChange={() => {
        const currentRouteName = navigationRef.current?.getCurrentRoute()?.name;
        if (currentRouteName && currentRouteName !== routeNameRef.current) {
          Joryio.trackScreen(currentRouteName);
          routeNameRef.current = currentRouteName;
        }
      }}
    >
      {/* ... */}
    </NavigationContainer>
  );
}

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

Αναγνώριση χρηστών

Καλέστε το identify μετά τη σύνδεση ή όταν γνωρίζετε ποιος είναι ο χρήστης:

// After login
Joryio.identify('user-123');

// With attributes
Joryio.identify('user-123');
Joryio.setAttributes({
  email: 'john@example.com',
  firstName: 'John',
  plan: 'premium',
});

Alias χρηστών

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

Joryio.alias('user-123');

Reset (αποσύνδεση)

Εκκαθαρίστε την ταυτότητα χρήστη και ξεκινήστε νέα ανώνυμη συνεδρία:

Joryio.reset();

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

// Set multiple attributes
Joryio.setAttributes({
  firstName: 'John',
  lastName: 'Doe',
  plan: 'premium',
  age: 28,
  isVIP: true,
});

// Set a single attribute
Joryio.setAttribute('favoriteColor', 'blue');

// Increment a numeric attribute
Joryio.incrementAttribute('loginCount', 1);
Joryio.incrementAttribute('totalSpent', 29.99);

// Remove an attribute
Joryio.unsetAttribute('temporaryFlag');

Push Notifications

Ρύθμιση με Firebase (React Native Firebase)

import messaging from '@react-native-firebase/messaging';

// Request permission
const authStatus = await messaging().requestPermission();

// Get and register token
const token = await messaging().getToken();
Joryio.registerPushToken(token);

// Listen for token refresh
messaging().onTokenRefresh((newToken) => {
  Joryio.registerPushToken(newToken);
});

Χειρισμός clicks Push Notification

import messaging from '@react-native-firebase/messaging';

// When app is in background and notification is tapped
messaging().onNotificationOpenedApp((remoteMessage) => {
  const trackingId = remoteMessage.data?.joryio_tracking_id;
  if (trackingId) {
    Joryio.trackPushClick(trackingId);
  }
});

// When app was killed and opened via notification
messaging()
  .getInitialNotification()
  .then((remoteMessage) => {
    if (remoteMessage?.data?.joryio_tracking_id) {
      Joryio.trackPushClick(remoteMessage.data.joryio_tracking_id);
    }
  });

Έλεγχος κατάστασης Push

const enabled = await Joryio.isPushEnabled();
console.log('Push enabled:', enabled);

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

Τα μηνύματα εμφανίζονται από μόνα τους. Εγκαταστήστε το SDK, στείλτε μια καμπάνια, και εμφανίζεται - σχεδιασμένο από τα native views, με τις γραμματοσειρές, τα χρώματα και τη σκοτεινή λειτουργία της εφαρμογής σας. Δεν χρειάζεται καμία σύνδεση.

Χρειάζεστε την υπόλοιπη ενότητα μόνο αν θέλετε να αποδίδετε τα μηνύματα σε React

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

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 και ο διακομιστής θα απορρίψει τις εμφανίσεις της.

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

Κάθε μήνυμα φέρει ένα kind που δηλώνει τη μορφή του. Διακλαδώστε σε αυτό:

kind	Τι φέρει	Πώς να το αποδώσετε
'native'	title, body, imageUrl, buttons	Στοιχεία React Native - <Text>, <Image>, <Pressable>
'html'	html, css	Ένα WebView

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

Η εγγραφή με onInAppMessage σταματά την απόδοση από το SDK και παραδίδει κάθε μήνυμα στον κώδικά σας, ώστε να το σχεδιάσετε με στοιχεία React Native. Δεν θα λάβετε δύο αντίγραφα.

Κάντε το αν θέλετε τα in-app μηνύματα να ταιριάζουν με το υπόλοιπο UI σας, ή αν η εφαρμογή δεν επιτρέπεται να συνδέει web view - οπότε εξαιρέστε και το artifact UI από το build (joryio-android-ui στο Android, το product JoryioUI στο iOS).

Ακρόαση μηνυμάτων

import { useEffect, useState } from 'react';
import Joryio, { type InAppMessage } from '@joryio/react-native';

function App() {
  const [message, setMessage] = useState<InAppMessage | null>(null);

  useEffect(() => Joryio.onInAppMessage(setMessage), []);

  return <>{message && <InAppMessageHost message={message} />}</>;
}

Απόδοση native μηνύματος

Το native περιεχόμενο είναι κείμενο, όχι markup. Βάλτε το σε ένα <Text> - περνώντας το σε WebView ή σε dangerouslySetInnerHTML θα επαναφέρατε ακριβώς τον κίνδυνο injection που το native αποφεύγει.

function InAppMessageHost({ message }: { message: InAppMessage }) {
  if (message.kind === 'native') {
    return (
      <View>
        {message.imageUrl && <Image source={{ uri: message.imageUrl }} />}
        {message.title && <Text style={styles.title}>{message.title}</Text>}
        <Text>{message.body}</Text>

        {message.buttons.map((button) => (
          <Pressable
            key={button.id}
            onPress={() => {
              if (button.action === 'url' && button.url) Linking.openURL(button.url);
              Joryio.trackInAppImpression(message.id, 'clicked');
            }}
          >
            <Text>{button.text}</Text>
          </Pressable>
        ))}
      </View>
    );
  }

  return <WebView source={{ html: `<style>${message.css}</style>${message.html}` }} />;
}

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

Το message.style φέρει τις παρακάμψεις που όρισε ο συντάκτης. Κάθε πεδίο είναι προαιρετικό και ένα πεδίο που λείπει σημαίνει κληρονόμηση της εμφάνισης της εφαρμογής σας - εφαρμόστε μόνο όσα υπάρχουν:

const st = message.style;
const text = {
  // 'auto': στοίχιση κατά τη γλώσσα του ΜΗΝΥΜΑΤΟΣ, όχι της συσκευής.
  writingDirection: 'auto' as const,
  textAlign: st?.textAlign === 'center' ? 'center' : 'auto',
  ...(st?.fontFamily ? { fontFamily: st.fontFamily } : {}),
};

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

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

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

await Joryio.initialize('jry_sdk_YOUR_KEY', 'api-eu1.joryio.com', {
  allowHtmlJsInAppMessages: true,   // προεπιλογή: false
});

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

Παρακολούθηση εμφανίσεων

// When message is displayed
Joryio.trackInAppImpression(message.id, 'displayed');

// When user clicks
Joryio.trackInAppImpression(message.id, 'clicked');

// When user dismisses
Joryio.trackInAppImpression(message.id, 'dismissed');

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

Επιλογή	Τύπος	Προεπιλογή	Περιγραφή
enableDebug	boolean	false	Ενεργοποιεί debug logging
logLevel	string	'info'	Επίπεδο log: debug, info, warn, error
batchSize	number	50	Συμβάντα ανά παρτίδα πριν από αυτόματη αποστολή (εγγενής προεπιλογή)
flushInterval	number	5000	Διάστημα αυτόματης αποστολής σε ms (εγγενής προεπιλογή)
sessionTimeout	number	1800000	Λήξη συνεδρίας σε ms (εγγενής προεπιλογή: 30 λεπτά)
trackSessionStart	boolean	true	Αυτόματη παρακολούθηση συμβάντων έναρξης συνεδρίας
userId	string	null	Προκαθορισμένο ID χρήστη κατά την αρχικοποίηση

Εργαλεία

// Flush events immediately (before app close, logout, etc.)
Joryio.flush();

// Get IDs
const anonymousId = await Joryio.getAnonymousId();
const userId = await Joryio.getUserId();       // null if not identified
const sessionId = await Joryio.getSessionId();

Υποστήριξη TypeScript

Το SDK είναι πλήρως τυποποιημένο. Εισαγάγετε types όπως χρειάζεται:

import Joryio, {
  type JoryioConfig,
  type UserAttributes,
  type InAppMessage,
} from '@joryio/react-native-sdk';