JewelSDK for React Native

A powerful React Native SDK for integrating AI-powered product recommendation carousels and analytics into your e-commerce application.

Features

• AI-Powered Recommendations: Multiple recommendation models (Similar Items, Frequently Bought Together, You May Like, Top Sellers)
• Customizable UI: Flexible carousel components that match your app's design
• Network Resilience: Built-in connectivity monitoring and error handling
• TypeScript Support: Full TypeScript definitions included
• Infinite Scroll: Built-in pagination support for large datasets

Requirements

• React Native >= 0.60.0
• React >= 16.8.0
• iOS 11.0+ / Android 6.0+ (API 23+)

Installation

IMPORTANT: This is proprietary software. You must have an active contract with JewelML to use this SDK.

npm install @jewel_ml/react-native-jewel-sdk
# or
yarn add @jewel_ml/react-native-jewel-sdk

Peer Dependencies

The SDK requires the following peer dependencies:

@react-native-community/netinfo (for network monitoring):

npm install @react-native-community/netinfo
# or
yarn add @react-native-community/netinfo

react-native-svg (for rating stars and icons):

npm install react-native-svg
# or
yarn add react-native-svg

For iOS, install pods:

cd ios && pod install && cd ..

Quick Start

1. Wrap Your App with JewelSDKProvider

import React from 'react';
import { JewelSDKProvider } from '@jewel_ml/react-native-jewel-sdk';

const App = () => {
  return (
    <JewelSDKProvider>
      {/* Your app components */}
    </JewelSDKProvider>
  );
};

export default App;

2. Initialize the SDK

import { useEffect } from 'react';
import JewelSDK from '@jewel_ml/react-native-jewel-sdk';

const App = () => {
  useEffect(() => {
    const initializeSDK = async () => {
      const success = await JewelSDK.initialize('your-api-key-here', false);
      if (success) {
        console.log('JewelSDK initialized successfully');

        // Optional: Set user ID for personalized recommendations
        JewelSDK.setUserId('unique-user-id');

        // Optional: Enable tracking (enabled by default)
        JewelSDK.startTracking(true);
      }
    };

    initializeSDK();

    return () => {
      JewelSDK.deinitialize();
    };
  }, []);

  return (
    <JewelSDKProvider>
      {/* Your app components */}
    </JewelSDKProvider>
  );
};

3. Add Carousel to Your Screen

import { JewelCarousel, JewelCarouselModel } from '@jewel_ml/react-native-jewel-sdk';

const ProductScreen = () => {
  return (
    <ScrollView>
      <JewelCarousel
        model={JewelCarouselModel.SimilarItems}
        itemId="product-123"
        onItemClick={(itemId) => {
          console.log('Item clicked:', itemId);
          // Navigate to product detail
        }}
        onCarouselView={(itemId, model) => {
          console.log('Carousel viewed:', itemId, model);
        }}
      />
    </ScrollView>
  );
};

Available Carousel Models

The SDK supports different types of recommendation models:

enum JewelCarouselModel {
  SimilarItems = 'B_prod',                          // Related Products
  FrequentlyBoughtTogether = 'F_prod',              // Frequently Bought Together
  YouMayLike = 'L_prod',                            // You May Also Like
  TopSellers = 'T_prod',                            // Top Sellers
  RecentlyViewedItems = 'recently-viewed-items-storage', // Recently Viewed
}

API Reference

JewelSDK

Main SDK class for initialization and configuration.

initialize(apiKey: string, isDebug?: boolean): Promise<boolean>

Initializes the SDK with your API key.

Parameters:

• apiKey (string, required): Your JewelML API key
• isDebug (boolean, optional): Enable debug logging (default: false)

Returns: Promise<boolean> indicating if initialization was successful

Example:

const success = await JewelSDK.initialize('your-api-key', true);

setUserId(userId: string): void

Sets the current user ID for personalized recommendations.

Parameters:

• userId (string, required): Unique identifier for the current user

Example:

JewelSDK.setUserId('user-12345');

startTracking(enabled: boolean): void

Enables or disables analytics tracking.

Parameters:

• enabled (boolean, required): Boolean to enable/disable tracking

Example:

JewelSDK.startTracking(true);

deinitialize(): void

Cleans up SDK resources. Call when unmounting your app.

Example:

useEffect(() => {
  return () => {
    JewelSDK.deinitialize();
  };
}, []);

JewelCarousel Component

Main carousel component for displaying product recommendations.

Props

interface JewelCarouselProps {
  model: JewelCarouselModel;              // Required: Recommendation model
  itemId: string;                         // Required: Current item ID
  title?: string;                         // Optional: Custom carousel title
  numberOfItems?: number;                 // Optional: Items to fetch (default: 20)
  minimumItems?: number;                  // Optional: Min items to display (default: 2)
  infiniteScrollOption?: boolean;         // Optional: Enable infinite scroll (default: true)
  carouselStyle?: CarouselStyle;          // Optional: Custom carousel styling
  cardStyle?: CardStyle;                  // Optional: Custom card styling
  onItemClick?: (itemId: string) => void; // Optional: Item click callback
  onCarouselView?: (itemId: string, model: JewelCarouselModel) => void; // Optional: View callback
  language?: "en" | "th";                 // Optional: Display language (default: "en")
  showRatings?: boolean;                  // Optional: Show product ratings (default: false)
  showDiscountTag?: boolean;              // Optional: Show discount percentage tag (default: true)
  testID?: string;                        // Optional: Test ID for testing
}

Example with Custom Styling

import { JewelCarousel, JewelCarouselModel, CarouselStyle, CardStyle } from '@jewel_ml/react-native-jewel-sdk';

const customCarouselStyle: CarouselStyle = {
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    color: '#1a1a1a',
  },
  cardSpacing: 20,
  backgroundColor: '#f9f9f9',
};

const customCardStyle: CardStyle = {
  // Text styling
  itemName: {
    fontSize: 14,
    fontWeight: '600',
    color: '#000000',
  },
  brand: {
    fontSize: 12,
    color: '#666666',
  },
  price: {
    fontSize: 13,
    color: '#333333',
  },
  salePrice: {
    fontSize: 13,
    fontWeight: 'bold',
    color: '#e74c3c',
  },
  // Price container layout
  priceContainer: {
    flexDirection: 'row',
    gap: 8,
    alignItems: 'center',
  },
  // Discount/Sales tag styling
  salesTag: {
    fontSize: 10,
    fontWeight: 'bold',
    color: '#FFFFFF',
  },
  salesTagContainer: {
    backgroundColor: '#FF6B6B',
    position: 'top-right', // Options: 'top-left' | 'top-right'
  },
  // Card container styling
  backgroundColor: '#FFFFFF',
  borderRadius: 12,
  shadow: true,
};

<JewelCarousel
  model={JewelCarouselModel.YouMayLike}
  itemId="product-456"
  title="You Might Also Like"
  numberOfItems={15}
  minimumItems={3}
  infiniteScrollOption={true}
  carouselStyle={customCarouselStyle}
  cardStyle={customCardStyle}
  language="en" // optional, default = main language
  showRatings={true} // optonal, default = false
  showDiscountTag={true} // optional, default = true
  onItemClick={(itemId) => {
    console.log('Item clicked:', itemId);
  }}
  onCarouselView={(itemId, model) => {
    console.log('Carousel viewed:', itemId, model);
  }}
/>

Displaying Ratings and Discount Tags

Control the visibility of product ratings and discount tags:

<JewelCarousel
  model={JewelCarouselModel.SimilarItems}
  itemId="product-123"
  showRatings={true}        // Show star ratings and review count
  showDiscountTag={true}    // Show discount percentage badge (default: true)
/>

Ratings Display:

• Set showRatings={true} to display product ratings as stars and review counts
• Ratings are shown below the product title
• Default: false

Discount Tag:

• Set showDiscountTag={true} to show a discount percentage badge on products
• The badge appears when salePrice < price
• Customize the badge using cardStyle.salesTag and cardStyle.salesTagContainer
• Position can be set to "top-left" or "top-right" (default: "top-right")
• Default: true

Style Objects

CarouselStyle

Customize the appearance of the carousel container and title.

interface CarouselStyle {
  title?: JewelTextStyle;      // Title text styling
  cardSpacing?: number;         // Spacing between cards
  backgroundColor?: string;     // Background color (hex)
}

CardStyle

Customize the appearance of recommendation cards.

interface CardStyle {
  itemName?: JewelTextStyle;    // Product name styling
  brand?: JewelTextStyle;       // Brand name styling
  price?: JewelTextStyle;       // Price styling
  salePrice?: JewelTextStyle;   // Sale price styling
  priceContainer?: {            // Price container layout
    flexDirection?: "row" | "column";
    gap?: number;
    alignItems?: "center" | "flex-start" | "flex-end";
    justifyContent?: "center" | "flex-start" | "flex-end";
  };
  discountContainer?: {         // Discount tag container styling
    backgroundColor?: string;
  };
  salesTag?: JewelTextStyle;    // Sales tag text styling
  salesTagContainer?: {         // Sales tag container styling
    backgroundColor?: string;
    position?: "top-left" | "top-right"; // Default: "top-right"
  };
  backgroundColor?: string;     // Card background color
  borderRadius?: number;        // Card border radius
  shadow?: boolean;             // Enable shadow effect
}

JewelTextStyle

Define text styling properties.

interface JewelTextStyle {
  fontSize?: number;            // Font size
  fontWeight?: string;          // Font weight
  color?: string;               // Text color (hex)
  fontFamily?: string;          // Font family
}

Custom Hooks

useCarousel

Custom hook for managing carousel data and state.

import { useCarousel, JewelCarouselModel } from '@jewel_ml/react-native-jewel-sdk';

const MyComponent = () => {
  const { recommendations, state, loadMore, hasMoreContent } = useCarousel({
    model: JewelCarouselModel.SimilarItems,
    itemId: 'product-123',
    numberOfItems: 20,
  });

  // Use recommendations data
};

useTracking

Custom hook for tracking events.

import { useTracking } from '@jewel_ml/react-native-jewel-sdk';

const MyComponent = () => {
  const { trackCarouselClick, trackCarouselView } = useTracking();

  const handleClick = () => {
    trackCarouselClick({
      itemId: 'product-123',
      model: 'B_prod',
      itemName: 'Product Name',
    });
  };
};

useSDKReady

Check if SDK is initialized and ready.

import { useSDKReady } from '@jewel_ml/react-native-jewel-sdk';

const MyComponent = () => {
  const isReady = useSDKReady();

  if (!isReady) {
    return <LoadingScreen />;
  }

  return <YourContent />;
};

Advanced Usage

Context API

Access SDK state throughout your app:

import { useJewelSDK } from '@jewel_ml/react-native-jewel-sdk';

const MyComponent = () => {
  const { isInitialized, healthCheckState, isOnline, isSDKReady } = useJewelSDK();

  return (
    <View>
      <Text>SDK Ready: {isSDKReady ? 'Yes' : 'No'}</Text>
      <Text>Online: {isOnline ? 'Yes' : 'No'}</Text>
    </View>
  );
};

Debugging

Enable Debug Mode

Initialize the SDK with isDebug: true to enable detailed logging:

await JewelSDK.initialize('your-api-key', true);

This will log:

• SDK initialization status
• Health check attempts and results
• Network connectivity changes
• API requests and responses
• Event tracking
• Carousel loading status

Log Categories

Debug logs are categorized for easier filtering:

• [SDK] - SDK initialization and lifecycle
• [API] - API requests and responses
• [HealthCheck] - Health check status
• [Network] - Network connectivity
• [Tracking] - Event tracking
• [InfiniteScroll] - Pagination and infinite scroll
• [CarouselViewModel] - Carousel state management

Error Handling

The SDK includes comprehensive error handling:

import { APIError, APIErrorType } from '@jewel_ml/react-native-jewel-sdk';

try {
  // SDK operations
} catch (error) {
  if (error instanceof APIError) {
    switch (error.type) {
      case APIErrorType.NoAPIKey:
        console.error('API key not configured');
        break;
      case APIErrorType.NetworkError:
        console.error('Network error:', error.originalError);
        break;
      case APIErrorType.HTTPError:
        console.error('HTTP error:', error.statusCode);
        break;
    }
  }
}

TypeScript Support

The SDK is written in TypeScript and includes complete type definitions. No need for @types packages!

import {
  JewelSDK,
  JewelCarousel,
  JewelCarouselModel,
  CarouselStyle,
  CardStyle,
  Recommendation,
  SalesTagPosition,
} from '@jewel_ml/react-native-jewel-sdk';

Troubleshooting

SDK not initializing

• Check that your API key is valid
• Ensure you have network connectivity
• Enable debug mode to see detailed logs

Carousel not showing

• Verify SDK is initialized before rendering carousel
• Check that itemId is valid
• Ensure minimum item requirements are met
• Look for error logs in debug mode

TypeScript errors

• Ensure you're using TypeScript 4.0+
• Check that peer dependencies are installed
• Run npm install or yarn install again

Support

For questions, issues, or feature requests:

• Email: [email protected]
• Documentation: https://docs.jewelml.io

License

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

PROPRIETARY LICENSE - See LICENSE file for full terms and conditions.

Key points:

• Available only to active JewelML clients with a valid contract
• License is revocable upon contract termination or non-payment
• Redistribution and reverse engineering are prohibited
• For licensing inquiries: [email protected]