T-SOFT/Uygulama Geliştirme/App proxy

App proxy

App proxy, uygulamanızın sayfalarını mağazanın kendi alan adında sunar. Ziyaretçi magaza.com/apps/sadakat/puanlarim adresini açar; mağaza isteği imzalar, uygulamanızın adresine iletir ve yanıtı ziyaretçiye gösterir. Sadakat sayfası, form, kargo takip ya da iade portalı gibi sayfalar için kullanın: adres mağazanındır, arama motorları sayfayı mağazanın sayfası olarak görür ve yanıtınızı mağaza temasının içinde gösterebilirsiniz.

App proxy OS2 ve V5 vitrinlerinde çalışır.

Tanımlama

tsoft.app.toml dosyasına [app_proxy] bölümünü ekleyin (tsoft-cli 3.27 ve sonrası) ve tsoft app deploy çalıştırın. Aynı ayar partner panelinde Uzantılar → Vitrinde altında da yapılır.

[app_proxy]
url = "https://uygulamaniz.com/proxy"
subpath = "sadakat"
AnahtarDeğer
urlİsteklerin iletileceği adres. https:// ile başlar; ? ya da # içermez. Sondaki / atılır
subpathMağazadaki yol: magaza.com/apps/<subpath>. Küçük harf, rakam ve tire; en çok 40 karakter, tireyle başlayıp bitemez

İki anahtarı da boş ("") bırakmak proxy'yi kaldırır. Market'teki bir uygulamanın yeni ya da değişen proxy'si market incelemesine gider; onaylanana kadar mağazalarda eski hali geçerlidir. Kaldırma incelemeye gitmez.

Mağaza sahibi yolu kendi mağazasında değiştirebilir (panelde Uygulamalarım → Mağaza adresi). Bu yüzden bağlantılarınızda yolu sabit yazmayın; her istekte gelen path_prefix değerini kullanın. İki uygulama aynı yolu isterse mağazaya önce kurulan uygulama yolu alır; diğeri, mağaza sahibi yollardan birini değiştirene kadar çalışmaz.

Yönlendirme

/apps/<subpath> ve altındaki her yol uygulamanıza gider. Yolun geri kalanı ve sorgu, url'nin sonuna eklenir:

Ziyaretçi:  https://<domain>/apps/sadakat/puanlarim?sayfa=2
Uygulama:   https://uygulamaniz.com/proxy/puanlarim?sayfa=2&shop=ornek-magaza.com&store_id=…&logged_in_customer_id=1042&path_prefix=%2Fapps%2Fsadakat&timestamp=1763290000&signature=…
  • Yöntemler: GET, HEAD, POST, PUT, PATCH, DELETE. GET ve HEAD dışındaki isteklerde gövde iletilir; gövde en çok 1 MB olabilir, büyükse ziyaretçi 413 görür. application/x-www-form-urlencoded ve JSON gövdeler iletilir; dosya yükleyen multipart/form-data formlar iletilmez, dosyayı doğrudan uygulamanıza yükletin.
  • İletilen başlıklar: Accept, Accept-Language, Content-Type, User-Agent; ayrıca X-Forwarded-For (ziyaretçinin IP'si), X-Forwarded-Host ve X-Forwarded-Proto. Ziyaretçinin çerezleri ve Authorization başlığı iletilmez.
  • Süre ve boyut: Bağlantı 3 saniyede, yanıt 10 saniyede gelmezse ya da yanıt gövdesi 2 MB'ı aşarsa ziyaretçi 502 görür.
  • Adres güvenliği: İstek yalnız url'deki sunucuya gider. Özel ağ, yerel ve bulut meta veri adreslerine çözülen bir alan adına istek gönderilmez.

İsteğe eklenen parametreler

Mağaza her isteğin sorgusuna şu parametreleri ekler. Ziyaretçinin gönderdiği aynı adlı parametreler önce silinir, yani bu değerleri yalnız mağaza belirler.

ParametreDeğer
shopMağazanın alan adı
store_idMağaza kimliği (UUID). Admin API'de ve webhook'larda gelen mağaza kimliğiyle aynıdır
logged_in_customer_idGiriş yapmış üyenin kimliği; ziyaretçi giriş yapmadıysa boş
path_prefixBu mağazadaki yol, örneğin /apps/sadakat
timestampİsteğin oluşturulduğu an (Unix saniyesi)
signatureİmza

İmzayı doğrulama

Her isteği işlemeden önce imzayı doğrulayın: logged_in_customer_id yalnız imza doğruysa güvenilirdir.

  1. signature dışındaki bütün sorgu parametrelerini (ziyaretçinin kendi parametreleri dahil) alın, değerlerini URL kodlamasından çözün.
  2. Anahtara göre sıralayın. Aynı anahtar birden çok kez geldiyse değerlerini , ile birleştirin.
  3. Her birini anahtar=değer olarak yazıp ayraçsız art arda ekleyin.
  4. Bu metnin, uygulamanızın imza sırrıyla HMAC-SHA256 özetini alın (küçük harf hex) ve signature ile sabit sürede karşılaştırın.
  5. timestamp 5 dakikadan eskiyse isteği reddedin.

İmza sırrı client_secret'tan ayrıdır. Partner panelinde Uzantılar → Vitrinde → App proxy → İmza sırrı altında görünür ve yenilenir. Sırrı yeniledikten sonra mağazalar birkaç dakika içinde yenisine geçer; bu sürede iki sırrı da kabul edin.

Örnek: sır tsps_ornekgizlisir, istek ?sayfa=2&shop=ornek-magaza.com&store_id=8f14e45f-ceea-467a-9575-1c3b2a1d7e10&logged_in_customer_id=1042&path_prefix=%2Fapps%2Fsadakat&timestamp=1763290000 ise imzalanan metin ve imza şudur:

logged_in_customer_id=1042path_prefix=/apps/sadakatsayfa=2shop=ornek-magaza.comstore_id=8f14e45f-ceea-467a-9575-1c3b2a1d7e10timestamp=1763290000
b11ab7540f7bd5fb3463143eeb05dd6cdebb643572d981f151c2bdbf318b3baf
import crypto from 'node:crypto';

export function verifyAppProxy(url, secret) {
    const params = new URL(url).searchParams;
    const signature = params.get('signature') ?? '';
    const grouped = {};
    for (const [key, value] of params) {
        if (key !== 'signature') (grouped[key] ??= []).push(value);
    }
    const message = Object.keys(grouped)
        .sort()
        .map((key) => `${key}=${grouped[key].join(',')}`)
        .join('');
    const expected = crypto.createHmac('sha256', secret).update(message).digest('hex');
    const fresh = Math.abs(Date.now() / 1000 - Number(params.get('timestamp'))) < 300;

    return fresh && signature.length === expected.length
        && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

PHP'de $_GET yerine ham sorgu metnini kullanın: $_GET aynı anahtarın tekrarlarını ve . içeren anahtarları değiştirir.

Yanıt

Mağaza yanıtınızın durum kodunu ve gövdesini ziyaretçiye iletir.

  • Başlıklar: Content-Type ve Content-Language iletilir; 3xx yanıtlarda Location da. Set-Cookie iletilmez; ziyaretçiyi tanımak için logged_in_customer_id kullanın.
  • Önbellek: Mağaza yanıtı her zaman Cache-Control: private, no-store ile gönderir; üyeye özel içerik paylaşılan bir önbelleğe girmez.
  • Yönlendirme: Mağaza 3xx yanıtı kendisi izlemez, ziyaretçiye iletir. Mağaza içinde kalmak için Location'ı path_prefix ile kurun (/apps/sadakat/tesekkurler).
  • Hata: Uygulamanıza ulaşılamazsa ziyaretçi 502 görür.

Mağaza temasının içinde gösterme

Yanıta X-Tsoft-Proxy-Layout: theme başlığını eklerseniz, istek GET ise ve yanıt 200 durumlu text/html ise mağaza gövdeyi kendi temasının üst ve alt bölümü arasında gösterir. Bu durumda tam bir HTML belgesi değil, sayfanın ana içeriğini gönderin. İçerikte bir <title> ya da <meta name="description"> varsa sayfanın başlığı ve açıklaması olur; yoksa mağazanınkiler kullanılır.

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-Tsoft-Proxy-Layout: theme

<section class="sadakat">
  <h1>Puanlarım</h1>
  <p>1.250 puanınız var.</p>
</section>

Başlık yoksa yanıt olduğu gibi gösterilir; tam bir HTML sayfası, JSON ya da dosya döndürebilirsiniz.

Sınırlar

  • Mağaza başına uygulama başına bir proxy yolu vardır.
  • Uygulamanın lisansı askıya alındığında, uygulama kaldırıldığında ya da T-Soft uygulamanın uzantılarını kapattığında yol çalışmayı bırakır (ziyaretçi mağazanın 404 sayfasını görür).
  • Yol değişiklikleri mağazalara birkaç dakika içinde ulaşır.
  • Mağaza bakımdaysa, demo şifresiyle korunuyorsa ya da yalnız üyelere açıksa (özel alışveriş) ziyaretçi uygulamanıza değil, mağazanın o sayfasına ulaşır.
  • /apps/ yolları mağazanın 404 kayıtlarına ve büyük harf / sondaki / yönlendirmelerine girmez; /apps/Sadakat de sadakat yoluna gider.