Geliştirici paneli inkiveta.com

Mini App

Mini App (kullanıcının gördüğü adıyla "mini uygulama"), kendi web sayfanı (HTML/JS) inkiveta'nın içinde tam ekran açmanı sağlar: bir menü, bir mağaza, bir oyun, bir rezervasyon ekranı… Telegram Mini App'leri için yazılmış kod burada da çalışır: inkiveta mobil uygulamasının içinde window.Telegram.WebApp hazırdır; web sürümü için sayfana tek bir betik eklersin (Köprü).

Nasıl açılır?#

  • Satır içi düğmede web_app: {"url": "https://..."}
  • Yanıt klavyesinde web_app düğmesi
  • setChatMenuButton ile menü düğmesi
  • Hızlı eylem (kind: "mini_app")
  • Mini App bildirimi: kullanıcı bildirime (telefondaki bildirim ya da bildirim merkezindeki satır) dokununca açılır; start_param initData.start_param'dadır
  • Bağlantı: https://inkiveta.com/@<kullanici_adi>?startapp=<parametre> — kullanıcı başlatınca sana /start gelir, parametre message.inki_start_param alanındadır. <parametre> en çok 64 karakterdir: harf, rakam, _ ve -. Uzun biçim https://app.inkiveta.com/bot/<kullanici_adi>?startapp=<parametre> aynı işi görür ve geçerli kalır; daha önce paylaştığın bağlantıları değiştirmen gerekmez. Kısa bağlantı uygulamanın eski sürümlerinde ve tarayıcıda uzun biçime yönlendirilir; iPhone'da tarayıcıda açılırsa önce inkiveta'da aç düğmeli kısa bir sayfa gösterir (iOS, yönlendirmeyle uygulamayı açmaz). Parametre olduğu gibi taşınır; start ve startapp birlikte gelirse start geçerlidir.

Alan adı doğrulama#

Mini App'in açılabilmesi için adresinin alan adının sana ait olduğunu kanıtlarsın:

  1. Atölye → Mini App'te adresi gir; Atölye sana bir doğrulama dizesi verir.
  2. Dizeyi ya https://<alan-adın>/.well-known/inkiveta-miniapp.txt dosyasına bir satır olarak koy ya da DNS'e _inkiveta-miniapp.<alan-adın> TXT kaydı olarak ekle.
  3. Doğrula'ya bas (dakikada en çok 6 deneme). Bekleyen doğrulama 7 gün geçerlidir.

Doğrulanmamış alan adında Mini App açılmaz, initData üretilmez ve login_url düğmeleri kabul edilmez (BOT_DOMAIN_INVALID).

  • Bir alan adı (host) yalnız bir uygulamaya ait olabilir.
  • Aynı uygulamanın test ve gerçek ortamı farklı host kullanmalıdır (ör. test.ornek.com ve app.ornek.com), çünkü çerezler portu ayırt etmez.
  • Sunucun Türkiye dışındaysa gerçek ortamda yurt dışı aktarım sözleşmesi gerekir (Gizlilik).

Köprü (Telegram.WebApp)#

Mobil uygulamada window.Telegram.WebApp ve eşdeğeri window.Inki.WebApp sayfa yüklenmeden hazırdır (uygulama enjekte eder); resmî telegram-web-app.js betiğini ayrıca yüklersen de çalışır.

Web sürümünde (web.inkiveta.com) Mini App, alan adından iframe + postMessage ile açılır ve tarayıcı çerçeveye betik enjekte ettirmez: köprü ancak senin yüklediğin betikle kurulur. Web desteği için sayfanın <head>'ine, kendi betiklerinden önce şunu ekle:

html<script src="https://web.inkiveta.com/inkiveta-web-app.js"></script>

Bu betik web'de mobildekiyle aynı yüzeyi kurar (Telegram.WebApp, Inki.WebApp, Inki.inkiRequestProfileAccess, Inki.inkiRequestFile, Inki.inkiJoinGameRoom, Inki.initData …; platform "web"). Mobil uygulamada köprü zaten varsa hiçbir şeyi değiştirmez, inkiveta dışında (çerçevesiz) açılırsa hiçbir şey kurmaz. Bunun yerine resmî telegram-web-app.js'i de yükleyebilirsin; o zaman Telegram.WebApp çalışır ama Inki web'de olmaz (aşağıdaki web notları). İkisini birlikte yüklersen önce bizimkini yükle.

Adresin hash'inde tgWebAppData, tgWebAppVersion, tgWebAppPlatform, tgWebAppThemeParams bulunur.

html<script>
  const tg = window.Telegram.WebApp;
  tg.ready();
  tg.expand();
  document.body.style.background = tg.themeParams.bg_color;   // uygulama temasına uy
  tg.MainButton.setText("Siparişi gönder").show().onClick(() => {
    tg.sendData(JSON.stringify({ urun: "kesim", saat: "14:30" }));  // bota message.web_app_data gelir
  });
</script>

Desteklenenler: tema renkleri, ana/ikincil düğme, geri düğmesi, sendData, openLink, openInvoice (Ink ödemesi), showPopup/showAlert/showConfirm, CloudStorage, DeviceStorage, SecureStorage, tam ekran, ana ekrana kısayol, konum, telefon numarası isteme, yazma izni isteme, ekran yönü kilidi, profil bilgisi izni, dosya isteği, Damla arama izni, oyun odası bileti, viewportChanged / safeAreaChanged olayları.

Yoktur (mağaza kuralları): biyometri, ivmeölçer, jiroskop, cihaz yönü sensörü ve kamera köprüleri — bunlarda isAvailable false döner. Dosya seçmek için <input type="file"> yerine dosya isteği kullan.

Telegram'dan farklı davranan olaylar#

Olayinkiveta'da
fullscreen_failedKullanıcı tam ekran onayını reddederse {error:"USER_DECLINED"}
location_requestedRet {available:false}; getLocation geri çağrısı null alır
phone_requested{status:"sent", contact:{phone_number, first_name, last_name?, user_id?}} (sunucu imzalı response dizesi yok)
data_send_failedYalnız inkiveta'da: sendData verisi sohbet botuna iletilemezse {error:"SENSITIVE_CONTENT"} (veri parola/kod gibi bir sır içeriyor) ya da {error:"UNKNOWN_ERROR"}; Mini App açık kalır
home_screen_addedAndroid'de isteğin sisteme iletildiği anlamına gelir; iOS her zaman home_screen_checked {status:"unsupported"}
inki_notification_openedYalnız inkiveta'da: Mini App'in zaten açıkken kullanıcı uygulamanın bir bildirimine dokundu. Sayfa yeniden yüklenmez, initData değişmez; olay {start_param, category} taşır. Telegram.WebApp.onEvent('inki_notification_opened', …) ya da onEvent('inkiNotificationOpened', …); web'de inkiveta-web-app.js aynı olayı iletir, yalnız resmî betikle Telegram.WebView.onEvent('inki_notification_opened', …)

initData'yı doğrula#

Mini App sunucuna istek atarken Telegram.WebApp.initData dizesini gönder; sunucunda mutlaka doğrula. Aksi hâlde herkes başka bir kullanıcı gibi davranabilir.

1. Token ile (HMAC) — Telegram algoritmasının aynısı:

pythonimport hashlib, hmac, time
from urllib.parse import parse_qsl

def init_data_dogru_mu(init_data: str, bot_token: str) -> bool:
    alanlar = dict(parse_qsl(init_data, keep_blank_values=True))
    gelen = alanlar.pop("hash", "")
    veri = "\n".join(f"{k}={v}" for k, v in sorted(alanlar.items()))   # signature DAHİL
    gizli = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
    hesap = hmac.new(gizli, veri.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(hesap, gelen) and time.time() - int(alanlar.get("auth_date", 0)) < 86400

Hazır doğrulayıcılar da çalışır: aiogram check_webapp_signature, @telegram-apps/init-data-node validate.

2. Token'sız (Ed25519) — Mini App'i token'ı bilmeyen ayrı bir sunucu doğrulayacaksa. inkiveta kendi Ed25519 anahtarıyla imzalar (Telegram'ın anahtarı değil). Açık anahtar getMe yanıtındaki inki_signature_public_key alanındadır (32 bayt, base64url, dolgusuz). Anahtar ortama göre farklıdır: test token'ıyla …/test/getMe çağırırsan test anahtarını alırsın. Önbelleğe al; imza tutmazsa getMe'yi yeniden çağır.

pythonimport base64
from urllib.parse import parse_qsl
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

def b64url(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

def imza_dogru_mu(init_data: str, bot_id: int, acik_anahtar: str) -> bool:
    alanlar = dict(parse_qsl(init_data, keep_blank_values=True))
    imza = alanlar.pop("signature", None)
    alanlar.pop("hash", None)
    if imza is None:
        return False
    veri = f"{bot_id}:WebAppData\n" + "\n".join(f"{k}={v}" for k, v in sorted(alanlar.items()))
    try:
        Ed25519PublicKey.from_public_bytes(b64url(acik_anahtar)).verify(b64url(imza), veri.encode())
        return True
    except Exception:
        return False
# auth_date'in 24 saatten eski olmadığını da denetle.
  • auth_date gerçek Unix zamanıdır; 24 saatten eski veriyi reddet.
  • query_id tek kullanımlıktır; answerWebAppQuery ile 24 saat içinde yanıtla (yalnız article sonucu).

Depolama ve izinler#

  • CloudStorage, DeviceStorage, SecureStorage ve çerezler uygulama ve ortam başına ayrıdır. inkiveta'nın oturumuna, şifreleme anahtarlarına ve diğer uygulamaların verisine erişilemez.
  • Konum, kişi, yazma izni, profil bilgisi, dosya isteği, Damla arama izni, tam ekran ve ana ekran kısayolu her seferinde kullanıcı onayıyla çalışır.

Ekran yönü#

Mini App ekranı varsayılan olarak kilitsizdir ve telefonun yön kilidine uyar: kullanıcı telefonu yan çevirince yatay/dikey döner (uygulamanın geri kalanı dikey kalır); iOS'ta yön kilidi, Android'de otomatik döndürme kapalıysa dönmez. Kilidi yalnız senin açık komutun aşar: lockOrientation() ya da Inki.inkiRequestOrientation('landscape' | 'portrait' | 'sensor'). Telegram.WebApp.lockOrientation() o anki yönde kilitler, unlockOrientation() açar; isOrientationLocked durumu gösterir. Kilit o oturumla sınırlıdır. Dönüşte viewportChanged (ve tam ekrandaysan safeAreaChanged) yeniden gelir; yerleşimini --tg-viewport-height ve safeAreaInset ile kur. Web sürümünde yön tarayıcıyla döner, lockOrientation() etkisizdir (hata vermez).

Yatay açılması gereken oyunlar için inkiveta uzantısı Inki.inkiRequestOrientation('landscape') var (Telegram'da yok; olay inki_request_orientation {orientation}): telefon dikey tutulsa bile ekran hemen yataya geçer, sol/sağ telefonun duruşuna göre seçilir. 'portrait' yalnız dikey, 'sensor' telefonun yön kilidini dikkate almadan telefonun duruşuyla döner, 'auto' isteği kaldırır (yön yeniden telefona ve yön kilidine bırakılır); son istek Inki.inkiOrientation'da. Geçersiz değer yok sayılır. İstek Mini App kapanınca düşer. Uygulama içinde window.Inki.inkiRequestOrientation her zaman vardır; aynı işlev Telegram.WebApp üzerinde de bulunur ve resmî telegram-web-app.js'i yüklesen de yeni nesneye yeniden bağlanır. Web sürümünde Inki yalnız inkiveta-web-app.js yüklüyse vardır ve tarayıcıda yön zorlanamaz (istek hata vermeden yok sayılır) — window.Inki && typeof Inki.inkiRequestOrientation === 'function' ile sına. Sensör verisi vermez; yalnız ekranın yönünü ister.

Geri jesti ve kaydırma çubuğu#

Sol kenardan sağa kaydırma geri demektir (iki platformda da): BackButton görünürken backButtonClicked gelir, değilse Mini App kapanır — sistem geri tuşuyla aynı. Sol kenarın ilk 24 px'inden başlayan yatay sürükleme bu jesttir; o şeritte kendi yatay kaydırma jestini kurma. Kaydırma çubukları gösterilmez: platform kök görünümün çubuğunu kapatır ve sayfana scrollbar-width:none + ::-webkit-scrollbar{display:none} kuralını ekler; kaydırma çalışmaya devam eder.

Profil bilgisi#

initData.user (ve login_url alanları) yalnız kullanıcının izin verdiği bilgiyi taşır. Kullanıcı izinleri uygulamayı başlatırken seçer, sonradan uygulama ayarlarından değiştirir:

İzinAlanlarİzin yoksa
Görünen ad (name)first_name, last_name (adın son kelimesi; tek kelimeyse yok)first_name = "Kullanıcı", last_name yok
Kullanıcı adı (username)usernamealan yok
Profil resmi (photo)photo_urlalan yok

Sayfan çalışırken eksik izni isteyebilirsin (inkiveta uzantısı):

jsInki.inkiRequestProfileAccess(['name', 'username', 'photo'], (r) => {
  // r.status: "allowed" | "cancelled"; r.fields: şu an verili olanlar; r.init_data: yeni imzalı initData (varsa)
  if (r.init_data) sunucunaGonder(r.init_data);   // sunucunda YENİDEN doğrula
});
  • Hepsi zaten verilmişse pencere açılmaz: allowed döner, init_data gelmez (elindeki initData günceldir).
  • Eksik varsa kullanıcıya bir alt sayfa açılır: üstte uygulamanın adı ve geliştiricisi, altında istenen her alan ve bu alanla gidecek değer. Tek alan istersen "İzin ver" / "Şimdi değil" sorulur. Mobil uygulamada birden çok alan istersen her alanın kendi anahtarı vardır (varsayılan açık); kullanıcı yalnız bir kısmını verebilir. Web sürümünde pencere şimdilik istenen alanların hepsini birlikte sorar; sayfan iki durumu da r.fields üzerinden aynı şekilde ele alır.
  • Kısmi rıza: r.fields yalnız gerçekten verilmiş alanları taşır, istediklerinin hepsini değil. En az bir alan verildiyse allowed + yeni init_data gelir (Telegram.WebApp.initData / initDataUnsafe da güncellenir); hiçbiri verilmediyse cancelled. Hangi alanın geldiğini r.fields'tan oku, sayfanı verilmeyen alan olmadan da çalışır tut.
  • Kullanıcının kapattığı (reddettiği) alan bir daha sorulmaz; istersen yeniden açabileceği yeri söyle: ⋯ menüsü › İzinleri yönet. İstediğin alanların hepsi önceden reddedildiyse pencere açılmadan cancelled döner.
  • Olay adı inki_request_profile_access {fields}, yanıt inki_profile_access_requested; WebApp.onEvent('inkiProfileAccessRequested', …) da tetiklenir.
  • **photo_url** 24 saat geçerli imzalı bir adrestir; izin geri alınırsa ya da süre dolarsa 404 döner. Resmi kalıcı istiyorsan sunucunda indirip sakla, adresi saklama. Sayfanın CSP'si varsa img-src'ye https://app.inkiveta.com ekle (ya da resmi kendi sunucundan geçir).
  • Web sürümünde inkiveta-web-app.js yüklüyse Inki.inkiRequestProfileAccess mobildeki gibi çalışır; yalnız resmî telegram-web-app.js yüklüyse Inki yoktur: Telegram.WebView.postEvent('inki_request_profile_access', false, {fields}) gönder, Telegram.WebView.onEvent('inki_profile_access_requested', …) ile dinle. İşlev olarak sına: window.Inki && typeof Inki.inkiRequestProfileAccess === 'function'.

Dosya isteği#

Mini App'te <input type="file"> çalışmaz (sayfa cihazdaki dosyalara doğrudan erişemez). Kullanıcıdan dosya (Excel, fiş fotoğrafı, video…) almak için iste (inkiveta uzantısı):

jsInki.inkiRequestFile({ type: 'document' }, (r) => {
  // r.status: "sent" | "cancelled" | "failed"
  if (r.status === 'sent') sunucunaGonder({ initData: Telegram.WebApp.initData, file_id: r.file.file_id });
  if (r.status === 'failed') goster(r.error);   // "too_big" | "type" | "quota" | "upload"
});
  • type: photo | video | document (yoksa document). Kullanıcıya "<uygulama adı> bir dosya istiyor" penceresi açılır; "Seç" → inkiveta'nın kendi seçicisi → dosya uygulamana yüklenir. Sayfaya dosyanın kendisi gelmez, yalnız file: {file_id, file_unique_id, file_name?, mime_type, file_size}.
  • Sunucun initData'yı doğrular, sonra dosyayı getFile(file_id) ile çeker. file_id yalnız senin uygulamanda ve aynı ortamda geçerlidir.
  • Sınır: fotoğraf 10 MB (JPEG/PNG/WebP), video ve belge 20 MB. Tür içerikten doğrulanır.
  • Aynı anda tek istek ve tek pencere: süren istek varken gelen ikincisi cancelled alır. Dosya sohbette mesaj olarak görünmez, uygulamana update gitmez; sonucu kullanıcıya sayfanda göster.
  • Saklama: dosya platformda 24 saat kalır. Bu sürede aynı file_id'yi uygulamanın bir içeriğinde (mesaj gönderimi ya da düzenlemesi, bileşen ya da ana sayfa medyası, zengin mesaj, oyun fotoğrafı) kullanmazsan silinir; sonra getFile hata verir. getFile ile indirmek kullanım sayılmaz; akışa ya da sonra çalışacak bir yanıta yazmak da sayılmaz. Kalıcı gerekiyorsa 24 saat içinde kendi sunucuna indir. İçerikte kullandığın dosya kalır ve depo kotana girer. Aydınlatma metnini buna göre yaz (Gizlilik).
  • Olay adı inki_request_file {type}, yanıt inki_file_requested; WebApp.onEvent('inkiFileRequested', …) da tetiklenir. Web sürümünde inkiveta-web-app.js yüklüyse Inki.inkiRequestFile çalışır; yalnız resmî telegram-web-app.js ile: Telegram.WebView.postEvent('inki_request_file', false, {type: 'document'}) + Telegram.WebView.onEvent('inki_file_requested', …). İşlev olarak sına: window.Inki && typeof Inki.inkiRequestFile === 'function'.

Oyun odaları#

Gerçek zamanlı çok oyunculu oyun için Mini App bir oyun odasına doğrudan WebSocket ile bağlanır (inkiveta uzantısı). Tam anlatım: Oyun odaları.

jsInki.inkiJoinGameRoom(roomId, (r) => {
  // r.status: "issued" | "failed"; issued: r.ticket, r.url, r.expires_in (30), r.auth ("subprotocol" | "first_frame")
  if (r.status === 'issued' && r.auth === 'subprotocol') ws = new WebSocket(r.url, ['inko.v1', 'inko.bilet.' + r.ticket]);
});
  • Bilet tek kullanımlık ve 30 saniyeliktir; her yeniden bağlanma yeni bilet ister. r.auth "first_frame" ise bağlantı açılınca ilk ileti {"op":"bilet","t":"<ticket>"} olur.
  • Sunucusu olmayan Mini App odayı Inki.inkiCreateGameRoom(params, cb) ile kendisi açar ve davet bağlantısı alır (Sunucusuz Mini App).
  • Olay adları: inki_request_game_ticket {room_id} → inki_game_ticket_requested; inki_request_game_room {game_short_name?} → inki_game_room_requested. Web'de yalnız resmî telegram-web-app.js ile Telegram.WebView.postEvent(…) + Telegram.WebView.onEvent(…) kullan.
  • Sayfanın CSP'si varsa connect-src'ye wss://app.inkiveta.com ekle. İşlev olarak sına: window.Inki && typeof Inki.inkiJoinGameRoom === 'function'; yoksa kullanıcıya uygulamayı güncellemesini öner.

Kurallar#

  • Mini App içinden dijital ürün satışı yalnız openInvoice ile (Ink) yapılır; başka bir ödeme yöntemine yönlendirmek yasaktır (Ödemeler).
  • Uygulamanın Atölye kategorisi Oyun ise, ebeveyn denetiminde oyunları kapalı (ya da günlük oyun süresi dolmuş) kullanıcılarda Mini App açılmaz; kullanıcı nedenini görür, sana hiçbir şey gelmez.
  • Oyun odası kullanan her uygulamada (kategorisi ne olursa olsun) ebeveyn denetiminde oyunları kapalı kullanıcı odaya giremez: bilet isteği parental döner.
  • İmza anahtarı geçici olarak yapılandırılmamışsa (getMe'de inki_signature_public_key yoksa) Mini App açılmaz.