# SDK Kurulumu

Paket kurulumu ve başlatma
Kaynak: https://selwise.com/docs/mobile/setup

SDK'yı kurmak, API anahtarını oluşturmak ve başlatmak. Bu sayfayı bitirdiğinizde uygulamanız panelde **Data flow** kartında olay göndermeye başlamış olmalıdır.

## Gereksinimler

| | |
|---|---|
| Paket | `@selwise/react-native` (güncel sürüm 0.12.0) |
| React Native / Expo | Sürüm kısıtı koyulmamıştır; paket saf JavaScript'tir ve Hermes'te çalışır. Native modül olmadığı için Expo'da özel dev client gerekmez. |
| React | `react` 17 veya üstü, **isteğe bağlı** eş bağımlılık; yalnızca `@selwise/react-native/react` altındaki hook'lar için |
| Kalıcı depo | Uygulamanızın kendi `@react-native-async-storage/async-storage` paketi (önerilir, zorunlu değil) |
| WebView | `react-native-webview`; yalnızca [WebView köprüsü](/docs/mobile/webview-bridge) ve [özel widget](/docs/mobile/custom-widget) için, uygulamanızın kendi bağımlılığı olarak |
| Kanal | Panelde oluşturulmuş bir **Mobil Uygulama** kanalı |

```bash
npm install @selwise/react-native
npm install @react-native-async-storage/async-storage
```

Yarn kullanıyorsanız `yarn add` aynı paketleri ekler. Paket hem ESM hem CommonJS yayımlanır ve `sideEffects: false` işaretlidir. iOS ve Android'e özel bir kurulum adımı yoktur.

## Panelde hazırlık

1. Sol menüde **Kanallar** (Channels) grubundaki **Channels** satırında **Add Channel**'a basın, **What are you adding?** sorusunda **Mobile App**'ı seçin ve **Application Identifier** alanına bundle id'nizi (iOS) ya da paket adınızı (Android) ters DNS biçiminde yazın. Ayrıntı: [Uygulama Kanalları](/docs/channels/app-channels).
2. Kanal ekranında **Channel Overview** satırını açın. **Channel Key** kartı kanal anahtarınızı (`sk_` ile başlar) verir.
3. Aynı ekranda **Setup** kartı iki adım gösterir: **Create an API key** ve **Install @selwise/react-native**. İkinci adımın kod bloğu kanal anahtarınız yazılmış hâlde gelir.

### API anahtarını oluşturma

**Channels** listesinde kanalın satırındaki **⋮** menüsünden **API keys**'i açın (Channel Overview'daki **Channel Key** kartından **Manage** de aynı pencereyi açar). **Create a key** altında bir ad verin, **Purpose** olarak **Mobile app** seçin ve **Create key**'e basın.

- **Mobile app** amacı anahtara `mobile_read` ve `mobile_write` scope'larını birlikte verir. Başka amaçlar (**Server-side rendering**, **Consent sync**) uygulama için uygun değildir.
- Anahtar `swpk_live_` ile başlar ve 64 onaltılık karakter taşır. **Copy this key now** penceresinde yalnızca bir kez görünür; Selwise yalnızca özetini saklar. Kaybederseniz **Rotate** ile yenileyin: eski anahtar anında iptal olur.
- Anahtar uygulama paketinin içinde taşınır ve çıkarılabilir. Scope'ları yalnızca public okuma ile olay ve sipariş yazmayı kapsar; panel erişimi vermez. Sızarsa **Rotate** ya da **Revoke**.

> **Anahtar iki scope da taşımalı**
>
> Sunucu gerekli scope'u HTTP metodundan türetir: `GET` için `mobile_read`, diğer her şey için `mobile_write`. Öneri **ürünleri** uç noktası ziyaretçi bağlamını gövdede taşıyan bir `POST` olduğundan yalnızca `mobile_read` taşıyan bir anahtar öneri ürünlerinde, segment üyeliği sorgusunda, sipariş gönderiminde, kimliklendirmede ve bülten kaydında `403` alır. Olay gönderimi anahtarsız çalıştığı, konfigürasyon ve arama da `GET` olduğu için hata geç fark edilir; en sinsi sonucu segment hedefli kampanyaların sessizce gizlenmesidir.

## Başlatma

Paket bir **sınıf** verir, hazır nesne vermez. Uygulama başına tek örnek oluşturun ve açılışta bir kez başlatın:

```ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { Selwise } from '@selwise/react-native';

export const selwise = new Selwise();

export async function initSelwise(): Promise<void> {
  await selwise.init({
    channelKey: 'sk_...',            // Channel Overview > Channel Key
    apiKey: 'swpk_live_...',         // mobile_read + mobile_write
    storage: AsyncStorage,
    debug: __DEV__,
  });
}
```

`init()` kimliği çözer ve önceki açılıştan kalan kuyruğu yeniden göndermeyi başlatır. Ağ cevabını **beklemez**; ilk ekranı bloklamaz. Panelin Takip Ayarları ve kanal yapılandırması arkadan yüklenir.

- `init()` ikinci kez çağrılırsa yok sayılır. `channelKey` (ya da `siteKey`) veya `apiKey` eksikse `Error` fırlatır.
- `init()` bitmeden olay üreten `track()` çağrıları **sessizce atılır** (kuyruğa alınmaz); `trackScreenView`, `identify`, `getSurfaces`, `trackOrder` gibi diğer metotlar `[Selwise] call init() before using the SDK` hatası fırlatır. `setCart`, `getCart` ve `onCartChange` istisnadır ve `init()`'ten önce de çalışır. Tam liste: [API Referansı](/docs/mobile/reference).
- Uygulama arka plana gittiğinde kuyruğu gönderin:

```ts
import { AppState } from 'react-native';

AppState.addEventListener('change', (state) => {
  if (state !== 'active') void selwise.flush();
});
```

### Seçenekler

| Seçenek | Tür | Varsayılan | Not |
|---|---|---|---|
| `channelKey` | `string` | yok | Panelde **Channel Key**. `siteKey` ile aynı değerdir; ikisinden biri zorunlu, ikisi de verilirse `channelKey` kazanır. |
| `siteKey` | `string` | yok | Yayımlanmış adı; sonsuza dek desteklenir. |
| `apiKey` | `string` | yok | **Zorunlu.** `x-selwise-api-key` başlığında gider. |
| `apiUrl` | `string` | `https://api.selwise.com/api/v1` | Sürüm önekini (`/api/v1`) içerir; sondaki `/` atılır. |
| `storage` | `SelwiseStorage` | bellek | `getItem`, `setItem`, `removeItem` sözü veren herhangi bir nesne. |
| `consent` | `ConsentSnapshot` | `granted: true`, yalnızca `necessary` | Bkz. [Kimlik, Onay ve Kuyruk](/docs/mobile/identity-and-queue). |
| `siteUserId` | `string` | yok | Açılışta biliniyorsa giriş yapmış kullanıcı kimliği. |
| `batchSize` | `number` | `20` | İstek başına olay; 1 ile 200 arasına sıkıştırılır. |
| `flushIntervalMs` | `number` | `5000` | `0` zamanlayıcıyı kapatır; elle `flush()` çağırın. |
| `timeoutMs` | `number` | `10000` | İstek başına zaman aşımı. |
| `maxQueueSize` | `number` | `500` | Çevrimdışıyken tutulan olay sayısı; dolunca en eski silinir. |
| `debug` | `boolean` | `false` | Tanılama çıktısı `console.log`'a gider. |
| `testMode` | `boolean` | `false` | Yalnızca test modundaki kampanya ve widget'ları gösterir; bkz. [Kampanya ve Widget](/docs/mobile/surfaces#test-modu). |
| `clientPlatform` | `string` | `react-native` | `x-selwise-client-platform` başlığı. |
| `clientVersion` | `string` | SDK sürümü | `x-selwise-client-version` başlığı. |

> **Tablodaki varsayılanlar yalnızca ilk saniyeler içindir**
>
> `batchSize`, `flushIntervalMs`, `maxQueueSize` ve `debug` için **açıkça verdiğiniz değer her zaman önceliklidir**. Vermediğiniz her biri kanalın `/config` cevabından alınır ve cevap gelince tablodaki varsayılanın yerine geçer. Kanalda hiç ayar yapılmamışsa sunucu varsayılanları gelir: `batchSize` 50, gönderim aralığı 30 sn, `maxQueueSize` 100, yeniden deneme 3, çevrimdışı kalıcılık açık. Yani hiçbir şey vermeyen bir uygulama pratikte 50 olaylık partiler ve 30 saniyelik aralıkla çalışır. Paneldeki bu ayarlar (**Data Layer** ekranı) uygulama kanalında sol menüde görünmediği için uygulama kanalı için değerleri **`init()` seçenekleriyle** sabitleyin. Yeniden deneme sayısı ve çevrimdışı kalıcılık için `init()` seçeneği yoktur; yalnızca sunucu değerini alırlar. Uzaktan gelen hata ayıklama yalnızca **açabilir**, log isteyen uygulamayı susturmaz.

## Hook'lar için sağlayıcı

```tsx
import { SelwiseProvider } from '@selwise/react-native/react';

export function Root({ children }: { children: React.ReactNode }) {
  return <SelwiseProvider client={selwise}>{children}</SelwiseProvider>;
}
```

`SelwiseProvider` içinde `useSelwise()` başlatılmış istemciyi verir; dışında çağrılırsa hata fırlatır.

## Yerel sunucuya bağlanma

`apiUrl` sürüm önekini içerir: `http://localhost:3001/api/v1`. Öneki atlarsanız her çağrı `404` döner ve boş katalog gibi görünür. Android emülatöründe makinenizin `localhost`'una `10.0.2.2` ile ulaşılır; düz `http` için iOS'ta App Transport Security ve Android'de cleartext izni, uygulamanızın kendi ayarlarıdır.

## Doğrulama

1. Uygulamayı açın, birkaç ekran gezin ve `debug: true` ile Metro konsolunda `Initialised` ile `Sent N event(s)` satırlarını görün.
2. Panelde **Kanallar → Kanal Özeti** (Channels → Channel Overview) ekranında **Channel activity** altındaki **Data flow** kartında olay sayısının arttığını görün. Son olay eskiyse kart kurulumun durmuş olabileceğini söyler.
3. Bir test siparişi gönderin (`trackOrder`) ve aynı ekranda **Orders** kartından kontrol edin.

Olay gelmiyorsa [Sorun Giderme](/docs/mobile/troubleshooting)'ye bakın.

## Sırada ne var

- [Event Takibi](/docs/mobile/tracking)
- [Kimlik, Onay ve Kuyruk](/docs/mobile/identity-and-queue)