1. Recaptcha Elementine Genel Bakış

Kuika’nın Recaptcha elementi, uygulamalarınızı botlar ve otomatik işlemlere karşı korumak amacıyla kullanılır. Kullanıcıdan doğrulama alarak yalnızca gerçek kullanıcıların belirli işlemleri gerçekleştirmesine izin verir ve spam, kötü amaçlı istekler veya otomatik form gönderimlerini engeller.

Recaptcha elementi, özellikle form gönderimleri, kayıt (sign up), giriş (login), iletişim formları ve kritik işlem adımları gibi güvenlik gerektiren senaryolarda önemli bir rol oynar. Kullanıcı doğrulaması, arka planda çalışarak kullanıcı deneyimini minimum düzeyde etkilerken uygulama güvenliğini artırır.

Recaptcha elementi yalnızca web uygulamalarında desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Form gönderimlerinin korunması: İletişim formları, geri bildirim formları veya destek taleplerinde bot kaynaklı spam gönderimlerini engellemek için kullanılır.
• Kayıt (Sign Up) ve giriş (Login) ekranları: Otomatik hesap oluşturma veya giriş denemelerini önlemek amacıyla kullanıcı doğrulaması sağlar.
• Şifre sıfırlama ve doğrulama adımları: Şifre yenileme, e-posta doğrulama veya güvenlik adımlarında kötüye kullanım riskini azaltır.
• Ödeme ve kritik işlem adımları:  Sipariş oluşturma, ödeme başlatma veya önemli veri gönderimleri öncesinde gerçek kullanıcı doğrulaması yapmak için kullanılır.

2. Temel Özellikler

• Bot ve otomatik işlemlere karşı koruma sağlar. Recaptcha elementi, uygulamaya yapılan otomatik ve kötü niyetli istekleri engelleyerek yalnızca gerçek kullanıcıların işlem yapmasını sağlar.
• Güvenlik seviyesini artırır. Spam gönderimler, bot kayıtları ve otomatik saldırılara karşı uygulamanın genel güvenliğini güçlendirir.
• Doğrulama sonucunu aksiyonlarda kullanabilme. Recaptcha doğrulamasının başarılı veya başarısız olmasına göre farklı aksiyon akışları kurgulanabilir.

2.1. ReCaptcha Elementi Kullanımı İçin Gereken Ayarlar

ReCaptcha elementini kullanabilmek için, her platform (Web, Android, iOS) için farklı key bilgileri gerekmektedir. Google ReCaptcha hizmetinden alınacak bu anahtarlar, platforma özel olarak oluşturulmalıdır. Web, Android ve iOS için ayrı ayrı alınan key bilgileri, doğru doğrulama süreci sağlamak için her platforma özgü olarak Configuration Manager modülündeki Google Recaptcha alanına girilmelidir.

Google Console ReCaptcha Ayarları
Google ReCaptcha anahtarlarını almak için aşağıdaki adımları takip edin:

WEB Key Alma

1. Google ReCaptcha Anahtar Oluşturma sayfasına gidin.

2. "Go to reCAPTCHA" butonuna tıklayın.

3. "Select a project" butonuna basarak devam edin.

3. Proje yoksa New Project butonu ile yeni bir proje oluşturun. 

5. Proje adını girerek "Create" butonuna tıklayın.

6. Açılan sayfada "Enable" butonuna basın.

7. Ardından "Create Key" butonuna tıklayın.

8. "Display Name" alanını doldurun ve "Choose Platform Type" olarak "Website" seçin.
9. Açılan alana web sayfanızın domain adını girin ve "Done" butonuna basın.

10. Domain adı kaydedildikten sonra, Key Type alanından ilgili seçenekleri belirleyerek "Create Key" butonuna tıklayın.

11. Oluşturulan key, sayfada listelenecektir.
12.  Android ve iOS uygulamalar için de benzer adımları takip ederek key oluşturabilirsiniz. 

Android Key Alma

1. ReCaptcha sayfasında "Create Key" butonuna tıklayın.
2. "Display Name" alanını doldurun ve "Choose Platform Type" olarak "Android app" seçin.
3. "Bundle ID"’yi girin.
4. "Done" butonuna basarak kaydedin.
5. Gerekli seçenekleri belirleyerek "Create Key" butonuna tıklayın.
6. Oluşturulan key, sayfada listelenecektir.

iOS Key Alma

1. ReCaptcha sayfasında "Create Key" butonuna tıklayın.
2. "Display Name" alanını doldurun ve "Choose Platform Type" olarak "iOS app" seçin.
3. "Bundle ID"’yi girin.
4. "Done" butonuna basarak kaydedin.

5. Bundle ID’yi kayıt ettikten sonra hemen altında Apple Developer settings alanıyla devam edeceğiz. 
6. Apple Developer hesabınıza giriş yaparak Certificates, Identifiers & Profiles sayfasına gidin.

7. "Keys" sekmesinden "+" butonuna tıklayarak yeni bir "Private Key (.p8)" dosyası oluşturun.

8. "Key Name" girerek "Register" butonuna tıklayın ve "Download" butonuna basarak .p8 dosyasını indirin.

.p8 dosyası sadece bir kez indirilebilir.

9. İndirilen .p8 dosyasını ReCaptcha sayfasına yükleyin.

10. "Key Identifier" alanı için "Certificates, Identifiers & Profiles" bölümünden oluşturulan key’in "KEY ID"’sini alın.
11. "Team ID" alanı için, aynı sayfada sağ üstte isminizin altında görünen kodu kullanın.
12. Domain adı kaydedildikten sonra, Key Type alanından ilgili seçenekleri belirleyerek "Create Key" butonuna tıklayın.
13. Oluşturulan key, sayfada listelenecektir.

Kuika ReCaptcha Entegrasyonu

Bu aşamaya kadar Web, Android ve iOS key’leri oluşturduk. Şimdi aldığımız key’leri Kuika platformunda kullanacağız. 

Eğer mobil uygulama için kullanacaksanız öncelikle mobil uygulama oluşturmanız gerekmektedir. Mobil uygulama oluşturmak için ilgili içeriğimize ulaşabilirsiniz. 

WEB Entegrasyonu

1. "Configuration Manager" modülüne gidin.

2. "App Settings" sekmesinde ve "Google Recaptcha" alanını bulun. Detaylı bilgi için Configuration Manager içeriğimizi inceleyebilirsiniz. 
3. "Add New" butonuna tıklayın.

4. Açılan pencerede "Name" alanını isteğe göre doldurun.
5. "Site Key" ve "Secret Key" alanlarını, Google tarafından oluşturulan Web Key içindeki değerlerden alın.
6. Google Recaptcha sayfasına geri dönüp oluşturduğumuz web key içinde Key Details butonuna tıklanır.

7. Details sayfasında Integrations sekmesine gelinir ve “Integrate with a third-party service or plugin” butonuna tıklanır.
8. Gelen penceredeki ise Secret Key olur.
   
   • "ID" değeri -> "Site Key"
   • "Secret Key" değeri -> "Secret Key"
9. Gerekli bilgileri girdikten sonra Configuration Manager modülündeki alana kaydedin. Android ve iOS uygulamalar için de benzer adımları takip ederek konfigürasyon oluşturabilirsiniz. 

Android Entegrasyonu

1. "Configuration Manager" modülüne gidin.
2. "Android" sekmesinde sayfanın en altına inerek "Google Recaptcha" alanını bulun.
3. "Add New" butonuna tıklayın.
4. "Name" alanını isteğe göre doldurun.
5. "Site Key" alanına, oluşturduğunuz Android Key’in "ID" değerini girin.
6. Gerekli bilgileri girdikten sonra kaydedin.

iOS Entegrasyonu

1. "Configuration Manager" modülüne gidin.
2. "iOS" sekmesinde sayfanın en altına inerek "Google Recaptcha" alanını bulun.
3. "Add New" butonuna tıklayın.
4. "Name" alanını isteğe göre doldurun.
5. "Site Key" alanına, oluşturduğunuz iOS Key’in "ID" değerini girin.
6. Gerekli bilgileri girdikten sonra kaydedin.

Bu adımları tamamladıktan sonra, UI Design modülüne geri dönün. 

ReCaptcha elementine sağ kenardaki ADD VALIDATION butonundan Validation ekleyin.

Daha sonra, Recaptcha doğrulamasını eklemek istediğiniz butona OnClick→ Verification→ Verify ReCaptcha Token aksiyonunu ekleyin. Eğer çıkış işlemi gerekiyorsa, Logout aksiyonunu ekleyin.

Yani, Recaptcha doğrulaması eklemek için, doğrulama yapılması gereken butona Verify ReCaptcha Token aksiyonunu, çıkış yapılması gereken butona ise Logout aksiyonunu ekleyebilirsiniz.

 Daha fazla bilgi için "Verify ReCaptcha Token" dokümanını inceleyebilirsiniz. 

Hata ve Sorun Giderme

1. Eğer doğrulama başarısız oluyorsa, Google Console'da key yapılandırmalarını kontrol edin.
2. API çağrılarında hata alıyorsanız, secret key'in doğru girildiğinden emin olun.
3. Eğer reCAPTCHA elementi sayfada görünmüyorsa, UI tarafındaki entegrasyonu kontrol edin ve eksik olan aksiyonları tamamlayın.

2.2. Recaptcha Elementine Eklenebilen Aksiyonlar

Recaptcha elementi, herhangi bir aksiyonu desteklemez ve doğrudan işlem başlatmaz. Kullanıcı doğrulama durumunu yalnızca kontrol amaçlı sağlar ve güvenlik için bir kontrol noktası olarak kullanılır. Doğrulama sonucuna bağlı işlemler, Recaptcha dışındaki elementler veya süreçler üzerinden yönetilmelidir.

3. ReCaptcha Elementi Nasıl Kullanılır? 

Bu bölümde reCAPTCHA elementinin uçtan uca kullanımını örnek senaryolar üzerinden ele alacağız.

Senaryo: Sign In Ekranı – reCAPTCHA ile Güvenli Giriş

Bir iş yönetimi veya kurumsal uygulamada, kullanıcıların sisteme güvenli şekilde erişebilmesi için Sign In ekranı, reCAPTCHA doğrulaması entegre edilerek yapılandırılmıştır. Bu ekran, yetkisiz erişimleri ve otomatik giriş denemelerini engellemeyi hedeflerken kullanıcı deneyimini sade bir yapıda sunar.

Senaryoda:

• Kullanıcı, e-posta adresi ve parola bilgilerini girerek giriş işlemini başlatır.
• Giriş işlemi öncesinde, “Ben robot değilim” reCAPTCHA doğrulaması ile kullanıcı etkileşimi doğrulanır.
• reCAPTCHA doğrulaması tamamlanmadan giriş işlemi gerçekleştirilemez ve kullanıcıya bilgilendirici bir uyarı mesajı gösterilir.
• Doğrulama başarıyla tamamlandığında kullanıcı sisteme giriş yaparak uygulamanın ana ekranına yönlendirilir.

Adım 1 - Hazır Sign In Ekranına ReCaptcha Ekleme

UI Design modülünü açın:

• Akademi üzerinde bulunan ReCaptcha Settings sayfası üzerinden gerekli adımları izleyerek Site Key ve Secret Key anahtarlarını oluşturun.

Kullanılan ReCaptcha tipi V2 Checkbox olarak ayarlanmalıdır.

• Sol yan paneldeki Screens alanında her proje de hazır gelen Signin ekranına tıklayın.
  

• Ekranda giriş butonu üzerine Elements > Interactive > ReCaptcha elementini ekleyin.
  

• ReCaptcha elementinin yanındaki boşluğa tıklayın ve Col > Styling > Layout > Align > Dikeyde ve Yatayda Ortala olarak ayarlayın.

ReCaptcha’nın styling alanı mevcut değildir.

Adım 2 - Doğrulama Aksiyonunu Ekleme

• Sign in sayfası içersindeki Sign In to Your Account button elementine tıklayın. Button elementine Add Action > onClick > Verification > Verify Recaptcha Token aksiyonunu ekleyin.
  

• Eklenen aksiyonu aksiyon kutucuğu üzerine basılı tutarak ilk sıraya alın.
  

• Verify Recaptcha Token aksiyonu içerisindeki token alanına Components > Recaptcha > token tanımlamasını yapın.
  

• Sign In to Your Account button elementine tıklayın ve tanımlı aksiyonlarındaki Sign In aksiyonu içerisine seçeneklerinden Add Condition ile koşul ekleyin.
  

• Koşul tanımlamasını Field > Action Result > VerifyRecaptchaToken ve diper alanları aşağıdaki gibi tanımlayın.
  

• Son olarak ReCaptcha elementine tıklayın ve Add Validation alanından validasyon ekleyin.

İsteğe bağlı olarak ek bir validasyon eklenmediğinde, elementin kendi notification yapısı kullanılır.

• Condition 1 yazısına tıklayın ve koşulu aşağıdaki gibi tanımlayın.
  

• Invalid Message alanını “Lütfen reCAPTCHA doğrulamasını işaretleyin.” olarak güncelleyin.
  

Preview

Uygulama test edildiğinde, hazır giriş ekranında giriş işlemi sırasında reCAPTCHA doğrulaması zorunlu olacak şekilde yapılandırılmıştır. Kullanıcı doğrulamayı tamamlamadan giriş yapamaz ve doğrulama yapılmadığında ekranda bilgilendirici bir uyarı mesajı gösterilir. Bu yapı sayesinde giriş süreci hem güvenli hem de kontrollü bir şekilde yönetilirken, yetkisiz ve otomatik erişim denemelerine karşı ek bir güvenlik katmanı sağlanır.

4. Ortak Özellikler (Properties)

ReCaptcha elementi üzerinde yer alan bazı alanlar tüm UI elementlerinde ortak olarak kullanılır. Bu nedenle, aşağıdaki özelliklerin detaylı açıklamaları ilgili genel kılavuz sayfalarında yer almaktadır:

• Authorization (Yetkilendirme) Ayarları
• Visibility (Görünürlük)
• Editability (Düzenlenebilirlik)
• Style Panel (Stil Ayarları)

5. Kullanım Tavsiyeleri (Best Practices)

• Recaptcha doğrulaması başarılı olduğunda, aksiyon çalıştırmadan önce token veya doğrulama sonucunu kontrol edin.
• Hata durumlarında kullanıcıya açık ve yönlendirici mesajlar gösterin (ör. “Lütfen doğrulamayı tamamlayın”).

6. Kısıtlamalar

• Recaptcha elementi kullanıcı etkileşimi olmadan çalışmaz; otomatik olarak doğrulama yapılamaz.
• Yanlış veya eksik Recaptcha yapılandırması, form ve aksiyonların çalışmamasına neden olabilir.
• İnternet bağlantısı olmayan ortamlarda ReCaptcha doğrulaması yapılamaz.
• ReCaptcha, yalnızca doğrulama sağlar; kullanıcı kimliği veya yetkilendirme işlemi yapmaz. Bu kontroller ayrıca uygulanmalıdır.