Fashionoscope React Native SDK

The Fashionoscope React Native SDK provides a powerful set of tools to integrate Fashionoscope's AI-driven fashion recommendations and search capabilities directly into your React Native application.

Features

• Personalized Recommendations: Deliver tailored fashion suggestions to your users.
• Visual Search: Allow users to search for products using images.
• Text Search: Advanced text-based search for fashion items.
• User Action Tracking: Track user interactions to improve recommendation accuracy.
• Seamless Authentication: Automatic token management and device identification.

Installation

Install the SDK along with its peer dependencies:

npm install @fashionoscope/react-native-sdk @react-native-async-storage/async-storage
# or
yarn add @fashionoscope/react-native-sdk @react-native-async-storage/async-storage

Note: For iOS, don't forget to run npx pod-install or cd ios && pod install.

Initialization

Initialize the SDK at the root of your application (e.g., in App.tsx or index.js).

import { FashionoscopeSDK } from '@fashionoscope/react-native-sdk';

await FashionoscopeSDK.initialize({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://apiv2.fashionoscope.com',
  timeoutSeconds: 30, // Optional, defaults to 30
});

Authentication

The SDK handles anonymous tokens and device identification automatically. However, you can explicitly manage the session:

Login

Initializes or refreshes the authentication token.

await FashionoscopeSDK.login();

Logout

Clears the stored tokens.

await FashionoscopeSDK.logout();

API Reference

Recommendations

fullCombine

Gets complete combinations and similar products for a given product.

Request Parameters:

• productId (string): The ID of the product.
• combinCount (number): Number of combinations to return.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<FullCombineResult>

const result = await FashionoscopeSDK.fullCombine('p-123', 5);

similars

Gets similar products for a given product.

Request Parameters:

• productId (string): The ID of the product.
• similarCount (number): Number of similar products to return.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<SimilarsResult>

const result = await FashionoscopeSDK.similars('p-123', 10);

personalization

Gets personalized product recommendations.

Request Parameters:

• productId (string): The reference product ID.
• recommendationCount (number): Number of recommendations to return.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<PersonalizationResult>

fullPersonalization

Gets a more comprehensive set of personalized recommendations.

Request Parameters:

• productId (string): The reference product ID.
• recommendationCount (number): Number of recommendations to return.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<FullPersonalizationResult>

Search

textSearch

Performs a text-based search.

Request Parameters:

• query (string): The search string.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<TextSearchResult>

const result = await FashionoscopeSDK.textSearch('blue evening dress');

imageSearchUpload

Uploads a base64 encoded image to search for similar products.

Request Parameters:

• imageBase64 (string): The base64 string of the image.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<ImageSearchResult>

const result = await FashionoscopeSDK.imageSearchUpload(myBase64Image);
// result.result_id can be used for subsequent refinement

imageSearchSimilars

Refines an image search based on a specific product from a previous upload result.

Request Parameters:

• resultId (string): The result_id returned from imageSearchUpload.
• selectedIndex (number): The index of the product in the previous result.
• similarCount (number): Number of similar products to return.
• nativeUserId (string | null): (Optional) Your internal user ID.

Response: Promise<ImageSearchResult>

Event Tracking

trackUserAction

Tracks user interactions to refine the AI engine's understanding of user preferences.

Important Note: This method must be called AFTER every product click, search, or add to cart action, purchase action, favorite action etc. If it is not called, results for recommendation calls may be less relevant and image search results may be less relevant.

Parameters:

• eventType (UserActionEventType): The type of action (e.g., PRODUCT_CLICKED).
• eventSource (UserActionEventSource): Where the action occurred (e.g., HOME).
• productId (string | null): Product involved.
• variantId (string | null): Variant involved.
• merchantId (string | null): Merchant ID.
• searchText (string | null): Search text if applicable.
• metadata (Record<string, string> | null): Additional custom data.
• nativeUserId (string | null): Your internal user ID.

FashionoscopeSDK.trackUserAction(
  'PRODUCT_CLICKED',
  'HOME',
  'p-123',
  'v-456',
  'm-789',
  null,
  { campaign: 'summer_sale' }
);

Configuration

SDKConfig

Passed to the initialize method.

| Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | apiKey | string | Yes | Your unique Fashionoscope API key. | | baseUrl | string | Yes | The base URL for the Fashionoscope API (e.g., https://apiv2.fashionoscope.com). | | timeoutSeconds | number | No | Request timeout in seconds (default: 30). |

Data Models

Result Interfaces

The SDK uses TypeScript interfaces for all responses. Most results contain arrays of APIProduct or APICombineProduct objects.

| Interface | Field | Type | Description | | :--- | :--- | :--- | :--- | | Common Fields | status | number | Status code (e.g., 200 for success). | | | message | string | A human-readable message. | | FullCombineResult | combins | APICombineProduct[] | An array of suggested outfit combinations. | | | similars | APIProduct[] | An array of similar products. | | PersonalizationResult | products | APIProduct[] | Personalized product recommendations. | | ImageSearchResult | result_id | string | Unique ID for the image search session. | | | products | APIProduct[] | Products found matching the image. | | | image_base64 | string | The processed image in base64 (if applicable). |

Type Schemas

APIProduct

The core product data structure used across all recommendation and search results.

type APIProduct = {
  title: string;
  price: number;
  price_currency: string;
  url: string;
  product_id: string;
  
  brand_name?: string | null;
  original_title_tr?: string | null;
  price1?: number | null;
  catalog_name?: string | null;
  native_product_id?: string | null;
  site?: string | null;
  signature?: string | null;
  cart_label?: string | null;
  thumbnail_image?: string | null;
  gender?: string | null;
  size_labels?: Array<APISize> | null;
  bbox?: [number, number, number, number] | null;
  labels?: Array<DetectedProductLabel> | null;
  target?: boolean | null;
  index?: number | null;
  similars?: Array<APIProduct> | null;
  combins?: Array<APICombineProduct> | null;
};

APICombineProduct

Represents a curated outfit combination.

type APICombineProduct = {
  combined_thumbnail_url: string;
  items: Array<APIProduct>;
};

DetectedProductLabel

Labels detected by AI for a product.

type DetectedProductLabel = {
  name: string;
  group: string;
};

APISize

Available sizes and stock information.

type APISize = {
  pku: string;
  size: string;
  stock?: number | null;
};

Tracking Enums

UserActionEventType

| Value | Description | | :--- | :--- | | PRODUCT_FAVORITED | User liked/favorited a product. | | PRODUCT_UNFAVORITED | User removed a product from favorites. | | PRODUCT_ADDED_TO_CART | User added product to basket. | | PRODUCT_REMOVED_FROM_CART | User removed product from basket. | | PRODUCT_CLICKED | User clicked/viewed a product. | | PRODUCT_PURCHASED | User completed a purchase. | | SEARCH_QUERY | User performed a text search. |

UserActionEventSource

Indicates where the action originated:

• HOME, SEARCH, BASKET, PRODUCT_PAGE, PRODUCT_LISTING, OTHER

License

MIT