توکن اتصال خصوصی

این توکن فقط در ورژن ۲ (سنتریفیگو) استفاده می‌شود. در ورژن ۱ (منسوخ شده) توکنی لازم نیست و برای کانال خصوصی از stream_key استفاده می‌کنید. جزئیات در رویدادهای خصوصی کاربران آمده است.

کانال‌های عمومی (معاملات، قیمت‌ها و عمق بازار) بدون احراز هویت در دسترس می‌باشند، اما جهت عضویت در کانال خصوصی private:user#<userId> باید هنگام اتصال یک توکن JWT ارسال کنید.

دریافت توکن

POST /v3/auth/token/refresh

احراز هویت این درخواست با کوکی کاربر انجام می‌شود. به این معنی که کاربر باید از قبل لاگین کرده باشد و کوکی او همراه درخواست ارسال شود.

در مرورگر، این یعنی credentials: "include".

در صورتی که بیرون از مرورگر کار می‌کنید، مانند یک ربات یا اسکریپت سمت سرور، باید هدر Cookie را خودتان بسازید و ارسال کنید.

پاسخ:

{
  "result": {
    "ws_access_token": "<توکن اتصال>",
    "expires_in": 900,
    "token_type": "Bearer"
  },
  "message": "The operation was successful",
  "success": true
}

فیلد	توضیح
`result.ws_access_token`	توکنی که باید در دستور `connect` بفرستید
`result.expires_in`	اعتبار توکن بر حسب ثانیه. این مقدار را از همین پاسخ بخوانید و در کد ثابت ننویسید.
`result.token_type`	نوع توکن. برای اتصال سوکت به آن کاری ندارید.

نام کانال خصوصی داخل توکن است

این مهم‌ترین اثر توکن روی کد شما می‌باشد. سرور به محض برقراری اتصال، شما را عضو هر کانالی که در channels آمده است می‌کند و آن را در پاسخ connect گزارش می‌دهد.

{ "id": 1, "connect": { "client": "...", "expires": true, "ttl": 900, "subs": { "private:user#42": {} } } }

بنابراین توجه داشته باشید که برای کانال خصوصی نباید دستور subscribe ارسال کنید و با SDK هم نباید newSubscription() بسازید. در غیر این صورت پاسخ 105: already subscribed دریافت می‌کنید.

پیام‌های این کانال در SDK روی رویداد سطح client دریافت می‌شوند، نه روی یک subscription. نمونه‌ی کد در صفحه‌ی اتصال و عضویت آمده است.

تمدید توکن

توکن پس از مدت کوتاهی منقضی می‌شود، بنابراین توجه داشته باشید که نباید آن را در یک متغیر ذخیره کنید.

در صورتی که از SDK استفاده می‌کنید، به جای مقدار توکن یک تابع به آن بدهید. SDK هر بار که توکن منقضی شود، خودش دوباره آن تابع را صدا می‌زند.

const client = new Centrifuge("wss://api.wallex.ir/connection/websocket", {
  getToken: async () => {
    const res = await fetch("https://api.wallex.ir/v3/auth/token/refresh", {
      method: "POST",
      credentials: "include", // کوکی کاربر باید همراه درخواست برود
    });
    const body = await res.json();
    return body.result.ws_access_token;
  },
});

در صورتی که بدون SDK کار می‌کنید، این کار بر عهده‌ی خود شما می‌باشد. پاسخ دستور connect مقدار ttl را بر حسب ثانیه برمی‌گرداند.

{ "id": 1, "connect": { "client": "...", "expires": true, "ttl": 900, "ping": 25, "pong": true } }

قبل از پایان این مدت، توکن تازه دریافت کنید و دوباره connect کنید. در صورتی که توکن منقضی شود، خطای 109: token expired دریافت می‌کنید و اتصال با کد 3005 بسته می‌شود.

جهت دریافت توکن تازه همان POST /v3/auth/token/refresh را دوباره صدا بزنید. هر توکنی که این endpoint می‌سازد claim channels را دارد، بنابراین پس از تمدید هم عضویت کانال خصوصی برقرار می‌ماند.

ارسال توکن

توکن را داخل دستور connect ارسال کنید.

{ "id": 1, "connect": { "token": "<ws_access_token>" } }

خطاهای رایج

کد	معنی	راه‌حل
`103`	permission denied	کانالی را subscribe کرده‌اید که در توکن شما نیست.
`105`	already subscribed	برای کانال خصوصی دستور `subscribe` فرستاده‌اید. لازم نیست.
`109`	token expired	توکن منقضی شده است. توکن تازه بگیرید.
`3500`	invalid token	توکن معتبر نیست. یک توکن تازه بگیرید.