1. Chat Elementine Genel Bakış

Chat elementi, uygulamanıza gerçek zamanlı mesajlaşma yeteneği kazandıran etkileşimli bir iletişim elementidir. Kullanıcıların birbiriyle veya sistemle anlık mesajlaşmasını sağlayarak hızlı, akıcı ve dinamik bir iletişim deneyimi sunar.

Chat elementi; müşteri destek sistemleri, sosyal etkileşim alanları, ekip içi iletişim ekranları ve kullanıcı geri bildirim mekanizmaları gibi senaryolarda kullanılır. Mesaj gönderme, alma ve görüntüleme süreçlerinin tek bir yapı altında yönetilmesi, uygulama içi etkileşimi güçlendirir.

Chat elementi hem web hem de mobil uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Canlı destek ve müşteri hizmetleri sohbetleri
• Kullanıcılar arası birebir veya grup mesajlaşma
• Sosyal platformlarda yorum ve sohbet alanları
• Uygulama içi destek botları veya asistanlar
• Ekip içi iletişim ve geri bildirim ekranları

2. Temel Özellikler

• Gerçek zamanlı mesajlaşma desteği: Mesajlar anında gönderilir ve alıcıya eş zamanlı olarak iletilir.
• Gönderilen ve alınan mesajların ayrıştırılması: Kullanıcı mesajları ve karşı taraf mesajları görsel olarak ayırt edilir.
• Dinamik veri ve state entegrasyonu: Mesaj içerikleri state, datasource veya aksiyon çıktıları üzerinden yönetilebilir.
• Kullanıcı etkileşimini yöneten yapı: Mesaj gönderme, okuma ve yeni mesaj algılama gibi etkileşimler desteklenir.

2.1. Chat Elementi Özellikleri

• Datasource: Mesaj geçmişinin gösterileceği veri kaynağını seçebilirsiniz.
• Current User Name: Chat elementinin kullanıldığı ekranda mevcut kullanıcı bilgisini görüntüler.
• Dark Mode: Switch aktif hale getirildiğinde, chat elementini karanlık modda görüntüleyebilirsiniz.
• Show Profile Photo: Kullanıcıların profil fotoğraflarını göstermek için Switch’i aktif hale getirebilirsiniz.
• Show User Name: Kullanıcı isimlerini göstermek için Switch’i etkinleştirebilirsiniz.
• Allow Edit Message: Kullanıcının tüm mesajlarını düzenlemesine izin verir.
• Allow Delete Message: Kullanıcının tüm mesajlarını silmesine izin verir.
• Speech To Text: Kullanıcının mikrofondan konuşarak mesaj yazmasını sağlar. Cihaz mikrofonu ve tarayıcı izinleri kullanılarak sesli giriş metne dönüştürülür.

2.2. Chat Elementi ile Gerçek Zamanlı Mesajlaşma Entegrasyonu

Bu örnek senaryo, uygulama kullanıcılarının, müşteri destek temsilcileriyle gerçek zamanlı mesajlaşabildiği bir Chat ekranı tasarlamayı içerir. 

2.2.1.Veri Kaynağı Hazırlığı 

Kuika ile veri kaynağına hızlı bir şekilde yeni bir tablo ekleyerek Chat elementinin mesaj geçmişini tutabilirsiniz. Aşağıdaki adımları izleyin:

• Datasources modülüne gidin. 
• Sol panelde Tables başlığı yanındaki + ikonuna tıklayın.
• Açılan menüden New Table seçeneğini seçin.
• Create a New Table ekranında tabloya bir isim verin (örneğin: chatHistory) ve Next butonuna tıklayın.

Gerekli sütun bilgilerini girin:

• Column Name: ID
• Type: Guid
• Required: ✔️
• Unique: ❌
• Column Name: mesaj – Mesaj içeriği
• Type: String 
• Required: ❌
• Unique: ❌
• Column Name: userDisplayName – Gönderenin görünen adı
• Type: String 
• Required: ❌
• Unique: ❌
• Column Name: avatar – Profil fotoğrafı URL’si (isteğe bağlı)
• Type: Image
• Required: ❌
• Unique: ❌
• Column Name: mesajCreatedAt– Mesaj gönderim zamanı
• Type: DateTimeOffset
• Required: ❌
• Unique: ❌
• Column Name: mesajModifiedAt – Mesajın güncellenme zamanı
• Type: DateTimeOffset
• Required:❌
• Unique: ❌
• Column Name: username – Kullanıcının sistemsel kullanıcı adı
• Type: String (200)
• Required:  ❌
• Unique: ❌

Datasource Filtreleme:

• Mesajları yalnızca ilgili kullanıcılar görebilmelidir.
• Örnek filtre:

WHERE username = loggedInUser.username

• Her sütunu girdikten sonra ADD butonuna tıklayın.
• Tüm sütunları ekledikten sonra CREATE butonuna tıklayarak tabloyu oluşturun.

Bu veri kaynağı, Chat elementinde “Datasource” olarak seçilecektir.

2.2.2. Chat Elementi Ekleme 

• UI Design modülüne gidin.
• Sol panelden Special > Chat elementini seçin.
• Ekrana sürükleyip bırakın:
  
  • Eğer Column içine bırakılırsa: Sadece Chat elementi eklenir.
  • Eğer boş alana bırakılırsa: Otomatik olarak bir Row elementi ile birlikte gelir.

2.2.3. Chat Elementi Ayarları

Datasource

• Yukarıda oluşturulan chatHistory seçilir.
• Mesaj geçmişi buradan alınır.

Current User Name

• Giriş yapan kullanıcı adı bağlanır (örneğin: loggedInUser.name).
• Chat’te gönderici bilgisini ayırt etmek için gerekir.

Dark Mode

• Açık/Kapalı olarak ayarlanır.
• Gece teması isteyen kullanıcılar için kullanıcı deneyimini artırır.

Show Profile Photo

• Aktif hale getirilir.
• Avatar alanı kullanılarak mesaj balonlarında profil fotoğrafı gösterilir.

Show User Name

• Aktif hale getirilir.
• Farklı temsilcilerle yapılan sohbetlerde kimin yazdığı kolayca anlaşılır.

Allow Edit Message (Yalnızca web uygulamalarda kullanılabilir.)

• Aktif hale getirilir.
• Kullanıcı, tüm mesajlarını düzenleyebilir (örneğin: yazım hatası düzeltmek için).

Allow Delete Message (Yalnızca web uygulamalarda kullanılabilir.)

• Aktif hale getirilir.
• Kullanıcı, tüm mesajlarını silebilir (örneğin: yanlışlıkla gönderilen mesajları kaldırmak için).

Text To Speech (Yalnızca mobil uygulamalarda kullanılabilir.)

• Mesajların sesli olarak okunmasına izin verir.
• Görsel engeli olan kullanıcılar için erişilebilirliği artırır, mobilde sesli etkileşim imkânı sunar.

2.2.4. Aksiyon Tanımlama

Sayfa Yüklenirken Mesajların Getirilmesi

Chat ekranı açıldığında geçmiş mesajların otomatik olarak yüklenebilmesi için sayfaya özel bir Page Init aksiyonu tanımlanmalıdır. Bu sayede Chat elementi veri kaynağından (örneğin chatHistory tablosundan) verileri çeker ve sohbet geçmişini otomatik olarak gösterir.

PageInit Aksiyon Ekleme Adımları:

1. Chat ekranının bulunduğu sayfayı seçin.
2. Sağ panelden +ADD ACTION → pageInit → Managed DB → Get Record aksiyonunu seçin.
3. Aksiyon Adı: getChatHistory
4. Tablo: chatHistory
5. Gerekirse filtreleme (örneğin sadece oturum açmış kullanıcıya ait mesajlar) yapılabilir.
6. Bu aksiyonun sonucunda elde edilen veri, Chat elementinin Data Source ayarında kullanılır.

Bu işlem sayesinde kullanıcı sohbet ekranını her açtığında en güncel mesaj geçmişi otomatik olarak yüklenmiş olur.

Mesaj Gönderimi

Chat ekranında kullanıcıların mesaj gönderebilmesi için bir aksiyon oluşturulması gerekir. Bu aksiyon genellikle “Gönder” butonuna bağlanır ve kullanıcı mesajını veri kaynağına (chatHistory tablosuna) kaydeder.

Save Record Aksiyonu Ekleme Adımları:

1. UI Design modülünde, Chat elementinin yanına veya altına bir Button (örneğin “Gönder”) ekleyin.
2. Butonu seçin ve Properties panelinde:
   
   • + ADD ACTION menüsünden,
     onMessageSend → Managed DB → Save Record seçeneğini seçin.
3. Save Record Aksiyon Modu olarak Insert modunu seçin:
   
   • Bu mod, tabloya yeni bir kayıt ekler.
   • Eğer aynı Id’ye sahip kayıt varsa hata verir, bu yüzden yeni mesajlarda genellikle Id gönderilmez veya otomatik üretilir.
4. Tablo Seçimi: chatHistory tablosu
5. Tablo Kolonları ve Değerler:
   
   • mesaj: Chat1.message.text
   • userDisplayName: loggedInUser.name
   • avatar: loggedInUser.photo
   • username: loggedInUser.username
   • mesajCreatedAt: Now()

Özel Aksiyonlar:

Mesaj gönderimi sırasında daha fazla kontrol veya işlem gerekiyorsa, onMessageSend tetiklendiğinde aşağıdaki gibi özel aksiyonlar oluşturulup bağlanabilir:

• getUserChat → Kullanıcının bilgilerini çekmek için özel bir Get Record aksiyonu tanımlanabilir. username kolonuna göre çalışır.
• chatHistoryADD → Yeni mesajı tüm kolonlarıyla kaydeden özel bir Insert Record aksiyonu oluşturulabilir.
• getChatHistory → Sayfayı yenileyen özel bir Refresh Chat aksiyonu tanımlanabilir. Edit/Send/Delete işlemlerinden sonra çalıştırılmalıdır. Aksi halde mesajlar anlık olarak güncellenmez. Alternatif olarak Save Record aksiyonu Update modunda mesajCreatedAt kolonuna göre yapılandırılarak bu işlev sağlanabilir.

Mesaj Güncelleme

Kullanıcı bir mesajı düzenlediğinde, ilgili kayıt id'ye göre güncellenir.

Adımlar:

1. Chat1 bileşenini seçin.
2. Sağ panelden +ADD ACTION → onEditMessage → Managed DB → Save Record aksiyonunu seçin.
3. Aksiyon Modu: Update
4. Tablo: chatHistory
5. Properties:
   
   • AllowEditMessage > Components > Chat1.message.currentlyEditingMessageId
6. Güncellenecek Alanlar:
   
   • mesaj: Chat1.message.text
   • mesajModifiedAt: Now()

Özel Aksiyonlar:

• chatHistorySAVE → Güncelleme işlemi için sadece mesaj kolonuna özel bir Update Record aksiyonu oluşturulabilir.
• getChatHistory → Mesaj düzenlemeden sonra sohbetin güncellenmesini sağlayan özel bir Refresh Chat aksiyonu tanımlanabilir. Alternatif olarak, Save Record aksiyonunun Update modunda mesajCreatedAt üzerinden tetiklenmesi sağlanabilir.

Mesaj Silme

Kullanıcı mesajın yanındaki "sil" ikonuna bastığında, mesaj sistemden tamamen kaldırılır.

Adımlar:

1. Chat1 bileşenini seçin.
2. Sağ panelden +ADD ACTION → onDeleteMessage → Managed DB → Delete Record
3. Tablo: chatHistory
4. Properties:
   
   • AllowDeleteMessage > Components > Chat1.message.messageIdToBeDeleted

Özel Aksiyonlar:

• deleteChatMessage → id kolonuna göre özel bir Delete Record aksiyonu oluşturulabilir.
• getChatHistory → Silme işleminden sonra sohbetin anlık olarak güncellenmesini sağlayan özel bir Refresh Chat aksiyonu tanımlanabilir. Aksi halde silinen mesaj görünmeye devam eder. Bu ihtiyaç, Save Record aksiyonu ile Update modunda mesajCreatedAt üzerinden de çözülebilir.

2.2.5. Chat Elementi Kullanım Akışı

Kullanıcı tarafı:

• Uygulamaya giriş yapar.
• Chat ekranına gelir.
• Mesaj geçmişi otomatik olarak yüklenir.
• Yeni mesaj yazar ve gönderir.
• Gönderilen mesaj yanında kendi adı ve varsa profil fotoğrafı görünür.
• Son mesajını düzenleyebilir veya silebilir.

Destek temsilcisi tarafı:

• Aynı mesaj tablosunu izleyen ayrı bir Chat ekranı kullanır.
• Kullanıcıya mesaj gönderir.
• Tüm iletişim aynı veri kaynağı üzerinden anlık olarak görünür.

2.2. Elemente Eklenebilen Aksiyonlar

Chat elementi, kullanıcıların mesaj gönderme, düzenleme ve silme etkileşimlerine bağlı olarak olay (event) bazlı aksiyonlar tanımlanmasını destekler. Aksiyonlar, Chat elementinin kendisine değil; kullanıcı etkileşimleri sonucunda tetiklenen event’lere bağlanır.

Chat elementi için aksiyonlar, Properties > Add Action alanı üzerinden aşağıdaki event’ler aracılığıyla eklenebilir.

Desteklenen Aksiyon Tetikleyicileri

onMessageSend: Kullanıcı yeni bir mesaj gönderdiğinde tetiklenir.

Kullanım amaçları:

• Gönderilen mesajı state veya veri kaynağına kaydetmek
• Mesajı backend’e veya bir API’ye iletmek
• Gerçek zamanlı sohbet akışını güncellemek
• Otomatik yanıt (bot) veya bildirim tetiklemek

Örnek senaryo: Kullanıcı destek ekranında mesaj gönderdiğinde, mesaj backend’e kaydedilir ve karşı tarafa anında iletilir.

onEditMessage: Kullanıcı daha önce gönderdiği bir mesajı düzenlediğinde tetiklenir.

Kullanım amaçları:

• Düzenlenen mesaj içeriğini güncellemek
• Mesaj geçmişini senkronize etmek
• Güncelleme sonrası kullanıcıya bilgilendirme göstermek

Örnek senaryo: Kullanıcı yazım hatası olan mesajını düzenlediğinde, mesaj güncellenir ve sohbet akışında yeni haliyle gösterilir.

onDeleteMessage: Kullanıcı bir mesajı sildiğinde tetiklenir.

Kullanım amaçları:

• Mesajı veri kaynağından kaldırmak
• Sohbet akışını yeniden render etmek
• Silme işlemini loglamak veya denetlemek

Örnek senaryo: Kullanıcı gönderdiği mesajı sildiğinde, mesaj sohbet ekranından kaldırılır ve backend tarafında silinir.

Aksiyonlara İlişkin Temel Kurallar

• Chat elementi birden fazla event üzerinden aksiyon tetikleyebilir.
• Aynı event için birden fazla aksiyon tanımlanabilir.
• Mesaj bazlı işlemler genellikle dinamik veri ve state yönetimi ile birlikte kullanılır.
• AllowEditMessage özelliği kapalıysa onEditMessage tetiklenmez.
  
  

Chat elementi, özellikle gerçek zamanlı iletişim ve etkileşim yönetimi gerektiren uygulamalarda, aksiyonlarla birlikte kullanıldığında güçlü ve esnek bir yapı sunar.

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

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

Senaryo: Kullanıcılar Arası Mesajlaşma Uygulaması

Bu örnekte Chat elementi ile uygulamaya giriş yapan kullanıcıların mesajlaşabildiği basit bir sohbet ekranı oluşturulmuştur. Kullanıcı, mesaj alanına metin girerek Send butonu ile mesaj gönderir ve mesajlar anlık olarak listede görüntülenir.

Senaryoda:

• Mesajların sağ veya sol tarafta gösterimi, Username ile CurrentUsername alanlarının karşılaştırılması ile belirlenir. Kullanıcıya ait mesajlar sağda, diğer kullanıcıların mesajları solda gösterilir.
• Kullanıcı, gönderdiği mesajları düzenleyebilir veya silebilir. Yapılan işlemler sonrasında liste güncellenir ve konuşma akışı korunur.

Adım 1 - Veri Kaynağı Oluşturma

DataSources modülünde tablo oluşturma: 

• Datasources modülüne gidin. 
• Ardından Tables sekmesine gidin.
• “ChatMessages” adında yeni tablo oluşturun.
• Kurulması gereken tablo yapısı aşağıdaki gibidir:

• Önemli Alan adları:
  
  • Id: Mesajın benzersiz kimliği (MessageId olarak kullanılır)
  • Message: Mesaj içeriği
  • UserDisplayName: Kullanıcının ekranda görünen adı
  • Username: Kullanıcının sistem kullanıcı adı (sağ/sol ayrımı için kullanılır)
  • UserAvatar: Kullanıcıya ait avatar görseli
  • CreatedDate: Mesajın gönderilme tarihi
  • IsEdited: Mesajın düzenlenip düzenlenmediği‍
  • IsDeleted: Mesajın silinme durumu (soft delete için)

Adım 2 - Gerekli Aksiyonun Tanımlanması

Arayüzde verileri göstermek için: 

1. Örnek iki aksiyon tanımlamanız gerekir.
2. Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.

• Kullanıcı Bilgilerini Getiren Aksiyon  (GetUser):

SELECT UserName, ProfilePhotoUrl FROM KUser WHERE UserName = @CurrentUserName

Uygularken KUser kısmını silip tekrar KUser yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

• Mesaj Geçmişini Getiren Aksiyon  (GetChatMessages):

SELECT * FROM ChatMessages WHERE IsDeleted = 0 ORDER BY createdDate ASC

Uygularken ChatMessages kısmını silip tekrar ChatMessages yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

Adım 3 - Initial Action Ekleme

Başlangıçta anasayfada: 

• Liste üzerinde mevcut yüklenen dosyaların gösterimi için Add Action > Initial Action > Custom > Managed DB > GetUser aksiyonunu ekleyin.
  

• Sayfa mesajların başlangıçta ve işlemsiz süre aralığında yenilenmesi için sayfaya Recurring Action ekleyin.
  

• Sayfa açılışında güncelleme için triggerOnPageInit > Aktif ve yenileme için süre aralığını Interval > 3 saniye olarak tanımlayın.
•  Recurring Action içerisine Add Action > Custom > Managed DB > GetChatMessages aksiyonunu ekleyin.
  

Adım 4 - Chat Elementini Ekleme ve Aksiyon Tanımlama

Başlangıçta anasayfada: 

• Sol yan panelden Elements > Special > Chat elementini sayfaya sürükleyip bırakın.
  

• Mesaj gönderimi için Chat > Properties > onMessageSend > ManagedDb > Save Record aksiyonunu ekleyin.
  

• Save Record aksiyonu içerisinde Select Table > ChatMessages ve alanları aşağıdaki gibi tanımlayın.
  

• CreatedDate alanını Default > Now tanımlamasını yapın.
  

• IsDeleted alanını kapalı olarak bırakın.
• IsEdited alanını kapalı olarak bırakın.
  

• Message alanını element üzerinden almak için Components > Chat > message tanımlamasını yapın.
  

• UserAvatar alanına kullanıcı bilgilerini getiren aksiyonu bağlayın Action Results > GetUser > First > ProfilePhotoUrl
  

• UserDisplayName alanına Default > User > Current First Name mevcut kullanıcı adı tanımlamasını yapın.
  

•  Username alanına Default > User > Current Username mevcut kullanıcı maili tanımlamasını yapın.
  

•  Id alanına Default > New Guid tanımlamasını yapın.
  

•  Tanımlamalar sonucunda Save Record aşağıdaki gibi olacaktır.
  

•  Kayıt sonrası mesajları güncellemek için Chat > onMessageSend > Custom > Managed DB > GetChatMessages aksiyonunu ekleyin.
  

•  Düzenleme işlemi için kolaylık açısından Save Record aksiyonunu kopyalayın.
  

•  Chat elementine Add Action > onEditMessage alanından rastgele bir aksiyon ekleyin ve aşağıdaki şekilde eklenen aksiyon üzerine yapıştır seçeneğine basın.
  

•  Yeni kopyalanan Save Record aksiyonu içerisinde mesaj düzenlendiğinde oluşturma tarihinin değişmemesi için CreatedDate alanını kaldırın.
  

•  IsEdited alanını aktif hale getirin.
  

•  Id alanını düzenlenecek mesajın Id bilgisini Components > Chat > currentlyEditingMessageId > To Guid tanımlayın.
  

•  İçerik güncelleme sonrası mesajları güncellemek için Chat > onEditMessage > Custom > Managed DB > GetChatMessages aksiyonunu ekleyin.
  

•  Mesajı silmek için Chat > onDeleteMessage > ManagedDb > Delete Record aksiyonunu ekleyin.
  

Soft delete işlemi için Save Record kullanarak IsDeleted alanını True olarak ayarlayabilir ve filtreler üzerinden ilerleyebilirsiniz. Mevcut aksiyon filtreleme işlemini gerçekleştirmektedir. Tek yapmanız gereken Save Record kurgusunu ayarlamaktır.

•  Delete Record içerisinde Select Table > ChatMessages ve Id > Components > Chat > MessageToBeDeleted > To Guid tanımlamaların yapın.
  

• İçerik güncelleme sonrası mesajları güncellemek için Chat > onDeleteMessage > Custom > Managed DB > GetChatMessages aksiyonunu ekleyin.
  

•  Son durumda Chat elementi üzerindeki aksiyon tanımları aşağıdaki gibi olmalıdır.
  Preview:

Preview:

Chat elementi ile kullanıcılar karşılıklı olarak mesajlaşabilir ve konuşma akışını tek bir ekran üzerinden takip edebilir. Gönderilen mesajlar anlık olarak listelenir ve kullanıcıya ait mesajlar sağda, diğer kullanıcıların mesajları solda gösterilir. Her mesaj; kullanıcı adı, avatar bilgisi ve gönderim zamanı ile birlikte görüntülenir. Kullanıcılar mesaj gönderme, mevcut mesajları görüntüleme ve sohbet akışını kolayca takip etme işlemlerini bu yapı üzerinden gerçekleştirebilir.

Feridun:

John:

4. Ortak Özellikler (Properties)

Chat 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)

Chat elementini kullanırken aşağıdaki iyi uygulamalar, kullanıcılar arası iletişimi daha net, güvenli ve sürdürülebilir hale getirir:

• Mesaj aksiyonlarını mutlaka backend veya state ile senkronize edin. Gönderilen, düzenlenen veya silinen mesajların kalıcı olarak saklanması önerilir.
• onMessageSend event’ini ana tetikleyici olarak konumlandırın. Mesaj gönderimi sonrası çalışması gereken tüm işlemleri bu event üzerinden yönetin.
• Mesaj düzenleme ve silme yetkilerini kontrollü kullanın. AllowEditMessage gibi ayarları yalnızca gerekli senaryolarda aktif edin.
• Kullanıcı bilgilerini net gösterin. ShowUserName ve ShowProfilePhoto özellikleri, mesajların kime ait olduğunu açıkça belirtir.
• Gerçek zamanlı deneyimi destekleyin. Mesaj gönderimi sonrası sohbet akışının anında güncellenmesi kullanıcı memnuniyetini artırır.
• Uzun sohbetlerde performansı gözetin. Çok uzun mesaj listelerinde veri yükleme ve render işlemleri optimize edilmelidir.

6. Kısıtlamalar

• Chat elementi tek başına veri saklama yapısı içermez; mesajların kalıcılığı için backend veya datasource gereklidir.
• Aksiyonlar yalnızca desteklenen event’ler (onMessageSend, onEditMessage, onDeleteMessage) üzerinden tetiklenebilir.
• Gerçek zamanlı senaryolarda ağ gecikmesi veya bağlantı sorunları mesaj senkronizasyonunu etkileyebilir.