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"
| Anahtar | Değer |
|---|---|
url | İsteklerin iletileceği adres. https:// ile başlar; ? ya da # içermez. Sondaki / atılır |
subpath | Mağ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×tamp=1763290000&signature=…
- Yöntemler:
GET,HEAD,POST,PUT,PATCH,DELETE.GETveHEADdışındaki isteklerde gövde iletilir; gövde en çok 1 MB olabilir, büyükse ziyaretçi413görür.application/x-www-form-urlencodedve JSON gövdeler iletilir; dosya yükleyenmultipart/form-dataformlar iletilmez, dosyayı doğrudan uygulamanıza yükletin. - İletilen başlıklar:
Accept,Accept-Language,Content-Type,User-Agent; ayrıcaX-Forwarded-For(ziyaretçinin IP'si),X-Forwarded-HostveX-Forwarded-Proto. Ziyaretçinin çerezleri veAuthorizationbaş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
502gö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.
| Parametre | Değer |
|---|---|
shop | Mağazanın alan adı |
store_id | Mağaza kimliği (UUID). Admin API'de ve webhook'larda gelen mağaza kimliğiyle aynıdır |
logged_in_customer_id | Giriş yapmış üyenin kimliği; ziyaretçi giriş yapmadıysa boş |
path_prefix | Bu 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.
signaturedışındaki bütün sorgu parametrelerini (ziyaretçinin kendi parametreleri dahil) alın, değerlerini URL kodlamasından çözün.- Anahtara göre sıralayın. Aynı anahtar birden çok kez geldiyse değerlerini
,ile birleştirin. - Her birini
anahtar=değerolarak yazıp ayraçsız art arda ekleyin. - Bu metnin, uygulamanızın imza sırrıyla HMAC-SHA256 özetini alın (küçük harf hex) ve
signatureile sabit sürede karşılaştırın. timestamp5 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×tamp=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));
}
function verifyAppProxy(string $queryString, string $secret): bool
{
$grouped = [];
foreach (explode('&', $queryString) as $pair) {
if ($pair === '') continue;
[$key, $value] = array_map('urldecode', explode('=', $pair, 2) + [1 => '']);
$grouped[$key][] = $value;
}
$signature = $grouped['signature'][0] ?? '';
unset($grouped['signature']);
ksort($grouped, SORT_STRING);
$message = '';
foreach ($grouped as $key => $values) {
$message .= $key . '=' . implode(',', $values);
}
$expected = hash_hmac('sha256', $message, $secret);
$fresh = abs(time() - (int) ($grouped['timestamp'][0] ?? 0)) < 300;
return $fresh && hash_equals($expected, $signature);
}
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-TypeveContent-Languageiletilir;3xxyanıtlardaLocationda.Set-Cookieiletilmez; ziyaretçiyi tanımak içinlogged_in_customer_idkullanın. - Önbellek: Mağaza yanıtı her zaman
Cache-Control: private, no-storeile gönderir; üyeye özel içerik paylaşılan bir önbelleğe girmez. - Yönlendirme: Mağaza
3xxyanıtı kendisi izlemez, ziyaretçiye iletir. Mağaza içinde kalmak içinLocation'ıpath_prefixile kurun (/apps/sadakat/tesekkurler). - Hata: Uygulamanıza ulaşılamazsa ziyaretçi
502gö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/Sadakatdesadakatyoluna gider.