Öneri ve Arama

Uygulamada öneri şeritlerini almak: hook ile ya da doğrudan çağrıyla. SDK ürünleri ve şeridin başlığını verir; kartı uygulamanızın kendi bileşeni çizer. Arama için Arama.

Hook ile

import { SelwiseProvider, useRecommendationWidget } from '@selwise/react-native/react';

// kökte: <SelwiseProvider client={selwise}>{children}</SelwiseProvider>

function SimilarProducts({ productCode }: { productCode: string }) {
  const { products, widget, loading, trackImpression, trackClick } = useRecommendationWidget(
    'WIDGET_ID',
    { currentProductId: productCode }
  );

  useEffect(() => {
    if (products.length > 0) trackImpression();
  }, [products, trackImpression]);

  if (loading || products.length === 0) return null;

  return (
    <>
      <Text>{widget?.title}</Text>
      <FlatList
        horizontal
        data={products}
        keyExtractor={(p) => p.itemCode}
        renderItem={({ item, index }) => (
          <ProductCard
            product={item}
            onPress={() => {
              trackClick(item.itemCode, index);
              navigation.navigate('ProductDetail', { code: item.itemCode });
            }}
          />
        )}
      />
    </>
  );
}

useRecommendationWidget(widgetId: string, options?: { currentProductId?: string; enabled?: boolean }): {
  products: SelwiseProduct[];
  productCard: Record<string, unknown> | null;
  loading: boolean;
  error: Error | null;
  followsCart: boolean;
  widget: RecommendationWidgetSummary | null;   // başlık, alt başlık, görünüm tipi
  experiment: { experimentId: string; variantId: string } | null;
  reload: () => void;
  trackImpression: () => void;                  // bağlama başına bir kez
  trackClick: (itemCode: string, position?: number) => void;
}

widgetId panelde widget'ın kimliğidir. enabled: false ürün kodu çözülene kadar isteği bekletir. Hook, bileşen kaldırılınca ve her bağımlılık değişiminde isteği iptal eder; hızlı kaydırmada aynı widget birkaç kez bağlanıp kalkabilir.

Doğrudan çağrı

React ağacının dışında (servis, saga, middleware) istemciyi doğrudan kullanın:

const widgets = await selwise.getRecommendationWidgets('app://product');   // RecommendationWidgetSummary[]
const result = await selwise.getRecommendationProducts(widgets[0].id, { currentProductId: 'SKU-12345' });
if (result.hidden || result.products.length === 0) return;   // hiçbir şey çizme

const heading = result.widget?.title ?? widgets[0].title;
selwise.trackRecommendationImpression(result.widgetId, result.products.map((p) => p.itemCode));
selwise.trackRecommendationClick(result.widgetId, 'SKU-12345', 0);

• getRecommendationWidgets(pageUrl?) ekrana hedeflenmiş etkin widget'ları verir: id, name, title, subtitle, strategy, displayType, maxProducts, isTestMode, segmentIds, eligibilityFlags ve stil alanları. Liste sayfa hedeflemesine göre süzülür; 0.13.0'dan beri SDK test modunu ve segmenti de uygular: test modundaki bir şerit yalnızca testMode: true ile başlatılan istemciye, segment hedefli bir şerit yalnızca segmentin kabul ettiği ziyaretçiye döner (tarayıcı widget'ıyla aynı kural). Daha eski bir sürümde bu iki alanı siz okuyup uygulamalısınız.
• getRecommendationProducts(widgetId, context?, signal?) ziyaretçi bağlamıyla (kimlik, oturum, ziyaretçi) birlikte POST eder; bu yüzden mobile_write ister. context: currentProductId ve gerekirse cart (bir RecommendationCartContext; null sepet göndermez).
• Sunucu bir hata yaşarsa 200 ile { products: [] } döner; SDK boş liste verir ve hata fırlatmaz. Şeridin boş gelmesinin sebebi için debug: true ve Sorun Giderme.

Ürün alanları

interface SelwiseProduct {
  id: string; itemCode: string; title: string;
  price: number; currency: string; originalPrice?: number | null; discountRate?: number | null;
  imageUrl?: string | null; url?: string | null; brand?: string | null; categories?: string | null;
  rating?: number | null; reviewCount?: number | null;
  isNew?: boolean; isBestseller?: boolean; inStock?: boolean; stock?: number | null;
  sku?: string | null; description?: string | null; shortDescription?: string | null;
  productType?: string | null; categoryHierarchy?: string | null;
  explainability?: Record<string, unknown> | null;
  complement?: { role: string; relation: string; label: { tr: string; en: string } } | null;
}

Sunucu bunlara ek olarak cartCode (sepetin kabul ettiği kod; null ise itemCode geçerli), groupCode (kardeş ürünleri birleştiren grup anahtarı, kimlik değildir), hasVariants ve variants (variantCode, sku, size, color, price, stock, inStock) alanlarını da gönderir; bu dört alan 0.12.0 tip tanımında yoktur, TypeScript'te bir tür dönüşümüyle okuyun. Sepete eklemek için kullanılacak kod cartCode'dur (boşsa itemCode); bedenli kategorilerde variants[].variantCode. Bkz. Varyant Gruplama. complement yalnızca Tamamlayıcı stratejisinde doludur: rol başına sekme için role ile grupla, bakış (look) için label ile alt yazı yaz.

Gösterim ve tıklama

Web'de gösterim ve tıklama otomatiktir; mobilde arayüzü siz çizdiğiniz için bildirimi de siz yaparsınız.

SDK sepete ekleme işlemini yapmaz; uygulamanızın sepet servisi yapar. Olayı yine kaydedin: selwise.trackAddToCart(item.itemCode, { quantity: 1 }) (Event Takibi).

Sepeti tamamlayan şerit

Kargo Bedavaya Tamamla şeridi, uygulamanın setCart ile bildirdiği sepete göre ürün seçer; SDK sepeti yalnızca bu stratejiye ekler. Sepet bildirilmemişse şerit boş döner. useRecommendationWidget böyle bir şeridi sepetle birlikte kendiliğinden günceller (followsCart: true):

Durum	Hook ne yapar
Sepet değişti	300 ms bekler (art arda değişiklikler tek istek) ve şeridi yeniden sorar
Yeni ürünler geldi	Şerit ekranda kalır, kartlar yerinde değişir; loading true olmaz, ikinci gösterim sayılmaz
Sepet eşiği geçti	products boş olur; şeridi çizmeyin
Sepet bilinmiyor (setCart(null))	İstek atılmaz, products boş olur

Boşalıp sepet değişince yeniden dolan şerit yeni bir gösterimdir. setCart'taki codes sepetteki ürünlerin tekrar önerilmesini engeller (Sepet ve Dinamik İçerik). Hook kullanmayan uygulama aynı davranışı RecommendationWidgetLoader ile kurar (0.10.0 ve sonrası):

const loader = new RecommendationWidgetLoader(selwise, widgetId, { currentProductId }, (state) => {
  // state.products, state.followsCart, state.appearance (şerit boşken dolduğunda artar)
});
loader.load();
// kaldırılırken: loader.stop();

A/B deneyleri

Bir öneri widget'ı üzerindeki deney uygulamada da çalışır; widget'ı kimliğiyle çağıran uygulamanın kod değiştirmesi gerekmez. SDK, bir şeridin ürünlerini istemeden önce ziyaretçinin kolunu çözer (açılış başına bir kez sorulur).

Mod	Uygulamada
different_module	Kolun şeridi kontrol yerine çizilir; ürünler o şeridin kimliğiyle istenir. result.widgetId o şeridi, result.sourceWidgetId sizin istediğinizi anlatır
config_override	Şerit aynı kalır; kolun başlığı, alt başlığı, görünüm tipi ve stili result.widget'a uygulanır. Strateji ve ürün sayısını sunucu uygular, SDK kırpıp yeniden sıralamaz
Kolun şeride hiçbir şey çizmediği durum	hidden: true, ürün isteği atılmaz; çizmeyin

• Başlığı sabit metninizden değil widget?.title'dan çizin; yoksa başlık deneyinin iki kolu aynı görünür.
• Ziyaretçi, şeridin ilk gösterim bildiriminde deneye sayılır (her kol için açılış başına bir kez; test modundaki cihaz sayılmaz). Gösterim bildirmezseniz uygulama ziyaretçileri sonuçlarda görünmez.
• Deneyin Kitle adımı varsa şerit yalnızca eşleşen ekranda deneye girer; ekran adı, mobil cihaz, sunucunun bildirdiği ülke, ölçülen sepet, segmentler ve test modu değerlendirilir. Sayfa türü ya da ekrandaki ürün gibi yalnızca getSurfaces'a verilen bilgiyi isteyen kurallar şeritte eşleşmez; ziyaretçi canlı şeridi görür ve sayılmaz.
• Öneri deneylerinde holdout kolu kurulamaz; gelirse şerit çizilmez ve ziyaretçi sayılmaz.
• Sepeti okuyan bir şerit koyan kol, kolun şeridine göre değerlendirilir (0.11.0 ve sonrası; eski SDK herkese kontrolü gösterir ve kimseyi saymaz).

resolveRecommendationWidget(widget) aynı cevabı ürün istemeden verir; şeridi nasıl çizeceğinize önceden karar vermek için kullanılır.

Sayfa hedefleme

Öneri widget'ının mobilde görünmesi için panelde sayfa hedeflemesi sentetik ekran adlarınızla eşleşmelidir (app://product); bkz. Event Takibi ve Sayfa Hedefleme.