> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Örnek uygulama: SMS doğrulama kodları ve davetler

> Clean Beans örnek uygulamasının OneSignal kullanarak telefon numaralarını tek kullanımlık kodlarla nasıl doğruladığı ve kişileri SMS veya e-postayla nasıl davet ettiği.

Bu sayfa, gerçek bir uygulamayı baştan sona takip eden [Örnek uygulama: eksiksiz bir OneSignal entegrasyonu](https://documentation.onesignal.com/docs/tr/example-full-integration-overview.md) kılavuzunun bir parçasıdır. Uygulama, ortak yaşanan evler için bir temizlik nöbet çizelgesi olan **Clean Beans**'tir ve Expo (React Native) ile bir Supabase backend'i kullanılarak geliştirilmiştir.

Clean Beans, SMS'i push ve e-postanın iyi yapamadığı iki iş için kullanır: bir telefon numarasının onu yazan kişiye ait olduğunu kanıtlamak ve henüz uygulaması olmayan birine ulaşmak.

| Mesaj | Kime gönderilir | Tetikleyici |
| - | - | - |
| Doğrulama kodu | Oturum açmış bir kullanıcının az önce girdiği numara | Uygulamadan çağrı |
| Haneye davet | Hesabı olmayan birinin telefon numarası veya e-posta adresi | Uygulamadan çağrı |

Her ikisi de bir External ID'ye değil, bir telefon numarası veya e-posta adresi olan **ham bir iletişim bilgisine** gönderilir. Bu kılavuzdaki diğer tüm gönderimlerden temel fark budur.

## Tek kullanımlık bir kodla telefon numarasını doğrulayın \\

User Profile'da kullanıcı bir cep telefonu numarası ekleyebilir. Uygulama backend'den 6 haneli bir kodu SMS ile göndermesini ister, kullanıcı kodu yazar ve backend kontrol eder. Numara ancak bundan sonra doğrulanmış sayılır.

![Üç durumdaki telefon numarası kartı: numara girme, kod girme ve doğrulandı](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-phone-verification.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=ae377258019c7454d600dc86bb722cce)

Telefon numarası ekleme: numarayı girin, kodu girin, doğrulandı.

OneSignal kısa mesajı teslim eder. Kodu oluşturmaz veya kontrol etmez. Geri kalan her şey backend'inizin işidir.

**1. Bir kod oluşturun ve karma olarak saklayın**

Kod kriptografik bir rastgele kaynaktan gelir. Yalnızca kullanıcıya ve telefon numarasına bağlı, anahtarlı bir karma saklanır, böylece tablo tek başına kodlara geri dönüştürülemez. Anahtar, başka hiçbir şey için kullanılmayan özel bir gizli anahtar olan `OTP_HASH_SECRET`'tır. Ayarlanmamışsa her iki fonksiyon da çalışmayı reddeder.

```typescript supabase/functions/_shared/otp.ts theme={null}
export function generateCode(): string {
  const limit = 4_000_000_000; // a multiple of 1,000,000 below 2^32, so no code is more likely than another
  const buf = new Uint32Array(1);
  do {
    crypto.getRandomValues(buf);
  } while (buf[0] >= limit);
  return String(buf[0] % 1_000_000).padStart(6, '0');
}

export async function hashCode(secret: string, userId: string, phone: string, code: string): Promise<string> {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${userId}:${phone}:${code}`));
  return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, '0')).join('');
}
```

```typescript supabase/functions/send-otp/index.ts theme={null}
const { data: inserted, error: insertErr } = await supabase
  .from('phone_otp_codes')
  .insert({
    user_id: user.id,
    phone,
    code_hash: codeHash,
    expires_at: new Date(now.getTime() + OTP_TTL_MINUTES * 60_000).toISOString(),
  })
  .select('id')
  .single();
```

**2. Kodu OneSignal üzerinden SMS ile gönderin**

`include_phone_numbers` numarayı doğrudan hedefler. OneSignal numarayı daha önce hiç görmediyse onun için bir SMS aboneliği oluşturur.

```typescript supabase/functions/send-otp/index.ts theme={null}
const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  target_channel: 'sms',
  // Targets a raw phone number. OneSignal creates an SMS subscription
  // for it if one does not exist yet.
  include_phone_numbers: [phone],
  ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
  name: 'Phone verification code',
  contents: {
    en: `Your Clean Beans verification code is ${code}. It expires in ${OTP_TTL_MINUTES} minutes.`,
  },
};
```

**3. Kodu kontrol edin**

Backend kullanıcının yazdığının karmasını alır ve saklanan karmayla karşılaştırır. Her yanlış tahmin sayılır. Beş yanlış denemeden sonra kod geçersiz olur ve yeni bir kod istenmesi gerekir.

```typescript supabase/functions/verify-otp/index.ts theme={null}
const submittedHash = await hashCode(OTP_HASH_SECRET, user.id, phone, code);

if (!safeEqual(submittedHash, row.code_hash)) {
  const attempts = row.attempts + 1;
  await supabase.from('phone_otp_codes').update({ attempts }).eq('id', row.id);

  const left = OTP_MAX_ATTEMPTS - attempts;
  return jsonResponse({
    error: 'invalid_code',
    message: left > 0
      ? `That code is not right. ${left} ${left === 1 ? 'attempt' : 'attempts'} left.`
      : 'Too many wrong attempts. Request a new code.',
    attemptsLeft: Math.max(left, 0),
  }, 400);
}
```

**4. Numarayı bir SMS aboneliği olarak kaydedin**

Backend kodu onayladığında uygulama numarayı oturum açmış kullanıcıya ekler.

```typescript src/lib/phone.ts theme={null}
export async function confirmPhoneCode(phone: string, code: string): Promise<void> {
  await callFunction('verify-otp', { body: { phone, code } });
  OneSignal.User.addSms(phone);
}
```

Uygulama bunu her oturum açmadan sonra tekrarlar, böylece doğrulanmış bir numara kullanıcıyı yeni bir cihaza kadar takip eder.

```typescript src/lib/phone.ts theme={null}
export async function syncOneSignalSms(): Promise<void> {
  try {
    const phone = await loadVerifiedPhone();
    if (phone) {
      OneSignal.User.addSms(phone);
      console.log('[phone] SMS subscription synced');
    }
  } catch (e) {
    console.warn('[phone] syncOneSignalSms error:', e);
  }
}
```

> [!NOTE]
>
> E-postada olduğu gibi `addSms()` yöntemini `login()` sonrasında çağırın. Ham bir telefon numarasına yapılan gönderim, kimseye ait olmayan bir abonelik oluşturur. Oturum açılmış bir uygulamadan çağrılan `addSms()`, bu aboneliği kullanıcıya bağlar. O zamana kadar abonelik kontrol panelinde ayrı bir kullanıcı kaydı olarak görünür.

## Uç noktayı koruyun \\

İstek üzerine kısa mesaj gönderen bir fonksiyon her çalıştığında para harcar ve kötüye kullanım için bir hedeftir. Clean Beans şu sınırları uygular.

| Kural | Değer |
| - | - |
| Kod ömrü | 10 dakika |
| İzin verilen yanlış deneme | 5 |
| Yeniden göndermeden önce bekleme | 30 saniye |
| Kullanıcı başına kod | 10 dakikada 3 |
| Kod başına kullanım | Bir. Yeni bir kod öncekinin yerini alır |

```typescript supabase/functions/send-otp/index.ts theme={null}
const MAX_CODES_PER_WINDOW = 3;
const WINDOW_MINUTES = 10;
const RESEND_COOLDOWN_SECONDS = 30;
```

Doğrulanmış numara kendi tablosunda saklanır. Bu tabloya yalnızca backend yazabilir, bu yüzden uygulama bir numarayı doğrulanmış olarak işaretleyemez ve hanenin diğer üyeleri onu okuyamaz.

```sql supabase/migrations/028_phone_verification_and_invites.sql theme={null}
create table if not exists public.user_phones (
  user_id     uuid primary key references public.profiles(id) on delete cascade,
  phone       text not null,                       -- E.164, e.g. +14155551234
  verified_at timestamptz not null default now()
);
```

## Numaranın girildiği yerde izin isteyin \\

Bir telefon numarası tek başına ona mesaj gönderme izni değildir. Doğrulama kodları için telefon alanının yanında bir açıklama yeterlidir. Bu açıklama kimin gönderdiğini, ne göndereceğini, ücret uygulanabileceğini ve nasıl durdurulacağını belirtmelidir.

```tsx src/components/PhoneVerificationCard.tsx theme={null}
{/* Consent disclosure: must sit next to the phone field */}
<Text style={styles.disclosure}>
  Enter your mobile number to receive verification codes by text message from Clean Beans.
  Msg & data rates may apply. Reply STOP to opt out.
</Text>
```

## Henüz kullanıcı olmayan birini davet edin \\

Household ekranında bir üye, birini SMS veya e-postayla davet edebilir. Davet edilen kişinin hesabı, kayıtlı bir cihazı ve External ID'si yoktur. Backend, uygulamanın katılma ekranını açan bir bağlantıyla ham iletişim bilgisine gönderim yapar.

![Davet iletişim kutusu ve gönderdiği davet kısa mesajı](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-invitation.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=78d087c22898bc9876dbdd1f90c56033)

Bir ev arkadaşını SMS veya e-postayla davet etme ve aldığı mesaj.

Aynı uç nokta her iki kanalı da işler. SMS `include_phone_numbers` kullanır. E-posta, konu ve HTML gövdesi doğrudan isteğe eklenerek `email_to` kullanır.

```typescript supabase/functions/send-invite/index.ts theme={null}
const joinUrl = `${JOIN_URL}?code=${encodeURIComponent(household.invite_code)}`;

const onesignalPayload: Record<string, unknown> = channel === 'sms'
  ? {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'sms',
      // Raw phone number: OneSignal creates an SMS subscription if needed
      include_phone_numbers: [contact],
      ...(ONESIGNAL_SMS_FROM ? { sms_from: ONESIGNAL_SMS_FROM } : {}),
      name: 'Household invitation (SMS)',
      contents: {
        en: `${inviterName} invited you to join "${householdName}" on Clean Beans, the cleaning rota app. Join: ${joinUrl} Reply STOP to opt out.`,
      },
    }
  : {
      app_id: ONESIGNAL_APP_ID,
      target_channel: 'email',
      // Raw email address: OneSignal creates an email subscription if needed
      email_to: [contact],
      name: 'Household invitation (email)',
      email_subject: `${inviterName} invited you to Clean Beans`,
      email_preheader: `Join "${householdName}" and share the cleaning.`,
      email_body: buildInviteEmail(inviterName, householdName, joinUrl, household.invite_code),
      // Keep the join link exactly as written. Click tracking would wrap
      // it in a redirect, and it would stop opening the app directly.
      disable_email_click_tracking: true,
    };
```

Bağlantı, [Uygulamayı sıradan web bağlantılarından açın](https://documentation.onesignal.com/docs/tr/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links) bölümünde kurulan bir Universal Link'tir. İki ayrıntı onun çalışmaya devam etmesini sağlar:

* **E-posta tıklama izleme kapalıdır.** İzleme, bağlantıları bir izleme alan adından geçecek şekilde yeniden yazar ve yeniden yazılmış bir bağlantı artık uygulamayı açmaz.
* **SMS izlenen bir kısa bağlantı kullanmaz**, aynı nedenle.

Davet edilen kişi uygulamayı yükleyip oturum açtığında, uygulamanın `login()` ile `addEmail()` veya `addSms()` çağrıları, davetin oluşturduğu aboneliği yeni kullanıcısına bağlar.

> [!WARNING]
>
> Davet edilen kişi uygulamanızdan mesaj almayı kabul etmemiştir. İstenmeyen SMS ve e-postalara ilişkin kurallar ülkeden ülkeye değişir ve katı olabilir. Clean Beans bu akışı ham bir iletişim bilgisine gönderimin nasıl çalıştığını göstermek için içerir ve her üyeyi günde on davetle sınırlar. Bu kalıbı üretimde kullanmadan önce gönderim yaptığınız yerlerin kurallarını kontrol edin ve mesajın davet eden kişi tarafından kendi telefonundan gönderilmesini değerlendirin.

## Bilinmesi gerekenler \\

* **Bir gönderici gereklidir.** **Settings > SMS** bölümünde varsayılan bir gönderici seçin veya her istekle `sms_from` iletin. İkisi de yoksa istek "A valid number is required for 'From' field" hatasıyla reddedilir.
* **`200` yanıtı her zaman bir mesajın gönderildiği anlamına gelmez.** Yalnızca durum koduna değil, yanıtta bir mesaj `id` değeri olup olmadığına da bakın.
* **Numaraları E.164 biçiminde saklayın.** Bu biçim, artı işaretinin ardından ülke kodu ve numaradan oluşur. API'yi çağırmadan önce başka her şeyi reddedin.
* **OneSignal Verify yönetilen alternatiftir.** Kodları sizin için oluşturur ve kontrol eder. Clean Beans tüm akışı göstermek için kendi çözümünü oluşturur.

**Kontrol paneli kurulumu.** [SMS kurulumunu](https://documentation.onesignal.com/docs/tr/sms-setup.md) tamamlayın ve kullanıcılarınızın bulunduğu ülkelere ulaşabilen varsayılan bir gönderici seçin.

> [card] [Tek kullanımlık şifreler](https://documentation.onesignal.com/docs/tr/sms-verify.md)
>
> OneSignal Verify ve kendi çözümünüzü oluşturma.

> [card] [SMS izni ve toplama](https://documentation.onesignal.com/docs/tr/sms-opt-in-and-collection.md)
>
> İzin ve açıklama gereksinimleri.

> [card] [SMS API referansı](https://documentation.onesignal.com/reference/sms.md)
>
> Tüm SMS parametreleri.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.