バージョン: 4.x

クライアントオプション

IOファクトリオプション

`forceNew`

デフォルト値: false

新しいManagerインスタンスを作成するかどうか。

Managerインスタンスは、サーバーへの低レベル接続（HTTPロングポーリングまたはWebSocketで確立）を管理します。再接続ロジックを処理します。

Socketインスタンスは、サーバーにイベントを送信し、サーバーからイベントを受信するために使用されるインターフェースです。特定の名前空間に属します。

単一のManagerには、複数のSocketインスタンスを接続できます。

次の例では、3つのSocketインスタンス（1つのWebSocket接続）で同じManagerインスタンスを再利用します。

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product"); // the "product" namespace
const orderSocket = io("https://example.com/order"); // the "order" namespace

次の例では、3つの異なるManagerインスタンス（および3つの異なるWebSocket接続）が作成されます。

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product", { forceNew: true }); // the "product" namespace
const orderSocket = io("https://example.com/order", { forceNew: true }); // the "order" namespace

既存の名前空間を再利用しても、毎回新しいManagerが作成されます。

const socket1 = io(); // 1st manager
const socket2 = io(); // 2nd manager
const socket3 = io("/admin"); // reuse the 1st manager
const socket4 = io("/admin"); // 3rd manager

`multiplex`

デフォルト値: true

forceNewの反対: 既存のManagerインスタンスを再利用するかどうか。

const socket = io(); // 1st manager
const adminSocket = io("/admin", { multiplex: false }); // 2nd manager

低レベルエンジンオプション

情報

これらの設定は、同じManagerに接続されているすべてのSocketインスタンスで共有されます。

`addTrailingSlash`

v4.6.0で追加

デフォルトで追加されていた末尾のスラッシュを無効にできるようになりました。

import { io } from "socket.io-client";

const socket = io("https://example.com", {
  addTrailingSlash: false
});

上記の例では、リクエストURLはhttps://example.com/socket.io/ではなくhttps://example.com/socket.ioになります。

`autoUnref`

v4.0.0で追加

デフォルト値: false

autoUnrefをtrueに設定すると、Socket.IOクライアントは、イベントシステムに他のアクティブなタイマー/TCPソケットがない場合（クライアントが接続されている場合でも）、プログラムの終了を許可します。

import { io } from "socket.io-client";

const socket = io({
  autoUnref: true
});

参照: https://node.dokyumento.jp/api/timers.html#timeoutunref

`closeOnBeforeunload`

履歴

バージョン	変更点
v4.7.1	このオプションは、デフォルトで`false`になりました。
v4.1.0	最初の導入。

デフォルト値: false

ブラウザでbeforeunloadイベントが発行されたときに、接続を（サイレントに）閉じるかどうか。

このオプションがfalse（デフォルト値）に設定されている場合、ユーザーがページをリロードすると、SocketインスタンスはFirefoxではdisconnectイベントを発行します。

Example with Firefox when closeOnBeforeunload is set to false

注意

この動作はFirefox特有です。他のブラウザでは、ユーザーがページをリロードしても、Socketインスタンスはdisconnectイベントを発行しません。

このオプションをtrueに設定すると、すべてのブラウザで同じ動作になります（ページをリロードしてもdisconnectイベントは発行されません）。

Example with Firefox when closeOnBeforeunload is set to true

警告

アプリケーションでbeforeunloadイベントを使用している場合（「このページを離れてよろしいですか？」）、このオプションをfalseのままにしておくことをお勧めします。

詳細については、このissueを確認してください。

`extraHeaders`

デフォルト値: -

追加ヘッダー（サーバー側ではsocket.handshake.headersオブジェクトにあります）。

例

クライアント

import { io } from "socket.io-client";

const socket = io({
  extraHeaders: {
    "my-custom-header": "1234"
  }
});

サーバー

io.on("connection", (socket) => {
  console.log(socket.handshake.headers); // an object containing "my-custom-header": "1234"
});

警告

ブラウザ環境では、WebSocketトランスポートのみを有効にしている場合、ブラウザのWebSocket APIではカスタムヘッダーを提供できないため、extraHeadersオプションは無視されます。

import { io } from "socket.io-client";

const socket = io({
  transports: ["websocket"],
  extraHeaders: {
    "my-custom-header": "1234" // ignored
  }
});

ただし、Node.jsまたはReact Nativeでは動作します。

ドキュメント: WebSocket API

`forceBase64`

デフォルト値: false

WebSocket経由で送信されるバイナリコンテンツに対してbase64エンコーディングを強制するかどうか（HTTPロングポーリングでは常に有効）。

`path`

デフォルト値: /socket.io/

サーバー側で取得されるパスの名前です。

警告

サーバーとクライアントの値は一致する必要があります（間にパス書き換えプロキシを使用している場合を除く）。

クライアント

import { io } from "socket.io-client";

const socket = io("https://example.com", {
  path: "/my-custom-path/"
});

サーバー

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  path: "/my-custom-path/"
});

これはURI内のパスとは異なることに注意してください。URI内のパスは名前空間を表します。

例

import { io } from "socket.io-client";

const socket = io("https://example.com/order", {
  path: "/my-custom-path/"
});

Socketインスタンスは「order」名前空間に接続されています。
HTTPリクエストは次のようになります: GET https://example.com/my-custom-path/?EIO=4&transport=polling&t=ML4jUwU

`protocols`

v2.0.0で追加

デフォルト値: -

単一のプロトコル文字列またはプロトコル文字列の配列のいずれか。これらの文字列はサブプロトコルを示すために使用され、単一のサーバーが複数のWebSocketサブプロトコルを実装できるようにします（たとえば、指定されたプロトコルに応じて異なる種類のインタラクションを処理できるサーバーが必要な場合があります）。

import { io } from "socket.io-client";

const socket = io({
  transports: ["websocket"],
  protocols: ["my-protocol-v1"]
});

サーバー

io.on("connection", (socket) => {
  const transport = socket.conn.transport;
  console.log(transport.socket.protocol); // prints "my-protocol-v1"
});

参照

`query`

デフォルト値: -

追加のクエリパラメータ（サーバー側ではsocket.handshake.queryオブジェクトにあります）。

例

クライアント

import { io } from "socket.io-client";

const socket = io({
  query: {
    x: 42
  }
});

サーバー

io.on("connection", (socket) => {
  console.log(socket.handshake.query); // prints { x: "42", EIO: "4", transport: "polling" }
});

クエリパラメータはセッション中は更新できないため、クライアント側でqueryを変更しても、現在のセッションが閉じられて新しいセッションが作成された場合にのみ有効になります。

socket.io.on("reconnect_attempt", () => {
  socket.io.opts.query.x++;
});

注: 次のクエリパラメータは予約されており、アプリケーションでは使用できません。

EIO: プロトコルのバージョン（現在「4」）。
transport: トランスポート名（「polling」または「websocket」）。
sid: セッションID。
j: トランスポートがポーリングだが、JSONPレスポンスが必要な場合。
t: キャッシュバストに使用されるハッシュ化されたタイムスタンプ。

`rememberUpgrade`

デフォルト値: false

trueの場合、サーバーへの以前のWebSocket接続が成功した場合は、通常のアップグレードプロセスをバイパスし、最初にWebSocketを試行します。トランスポートエラー後の接続試行では、通常のアップグレードプロセスが使用されます。SSL/TLS接続を使用している場合、またはネットワークでWebSocketがブロックされていないことがわかっている場合にのみ、これをオンにすることをお勧めします。

`timestampParam`

デフォルト値: "t"

タイムスタンプキーとして使用するクエリパラメータの名前。

`timestampRequests`

デフォルト値: true

各リクエストにタイムスタンプクエリパラメータを追加するかどうか（キャッシュバスト用）。

`transportOptions`

v2.0.0で追加

デフォルト値: {}

トランスポート固有のオプション。

例

import { io } from "socket.io-client";

const socket = io({
  path: "/path-for-http-long-polling/",
  transportOptions: {
    websocket: {
      path: "/path-for-websocket/"
    }
  }
});

`transports`

履歴

バージョン	変更点
v4.7.0	`webtransport`が追加されました。
v1.0.0	最初の導入。

デフォルト値: ["polling", "websocket", "webtransport"]

Socket.IOサーバーへの低レベル接続は、次のいずれかの方法で確立できます。

HTTPロングポーリング：連続したHTTPリクエスト（書き込みにはPOST、読み込みにはGET）
WebSocket
WebTransport

以下の例では、HTTPロングポーリングトランスポートを無効にしています。

const socket = io("https://example.com", { transports: ["websocket"] });

注：この場合、サーバー側でスティッキーセッションは不要です（詳細はこちらこちら）。

デフォルトでは、まずHTTPロングポーリング接続が確立され、次にWebSocketへのアップグレードが試みられます（説明はこちら）。WebSocketを最初に使用する場合は、

const socket = io("https://example.com", {
  transports: ["websocket", "polling"] // use WebSocket first, if available
});

socket.on("connect_error", () => {
  // revert to classic upgrade
  socket.io.opts.transports = ["polling", "websocket"];
});

可能性のある欠点の1つは、CORS設定の有効性は、WebSocket接続の確立に失敗した場合にのみチェックされることです。

`upgrade`

デフォルト値: true

クライアントがHTTPロングポーリングからより優れたトランスポートにアップグレードを試みるかどうか。

`withCredentials`

履歴

バージョン	変更点
v4.7.0	Node.jsクライアントは現在、`withCredentials`設定を尊重します。
v3.0.0	`withCredentials`は、現在`false`がデフォルトです。
v1.0.0	最初の導入。

デフォルト値: false

クッキー、承認ヘッダー、またはTLSクライアント証明書などの資格情報を含めてクロスサイトリクエストを送信するかどうか。withCredentialsの設定は、同一サイトのリクエストには影響しません。

import { io } from "socket.io-client";

const socket = io("https://my-backend.com", {
  withCredentials: true
});

サーバーは、接続を許可するために適切なAccess-Control-Allow-*ヘッダーを送信する必要があります。

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  cors: {
    origin: "https://my-frontend.com",
    credentials: true
  }
});

警告

withCredentialsをtrueに設定する場合は、origin: *を使用できません。これにより、次のエラーが発生します。

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at ‘.../socket.io/?EIO=4&transport=polling&t=NvQfU77’. (Reason: Credential is not supported if the CORS header ‘Access-Control-Allow-Origin’ is ‘*’)

ドキュメント

情報

バージョン4.7.0以降、withCredentialsオプションをtrueに設定すると、Node.jsクライアントはHTTPリクエストにクッキーを含めるようになり、クッキーベースのスティッキーセッションとの使用が容易になります。

Node.js固有のオプション

以下のオプションがサポートされています。

agent
pfx
key
passphrase
cert
ca
ciphers
rejectUnauthorized

Node.jsのドキュメントを参照してください。

自己署名証明書を使用した例

クライアント

import { readFileSync } from "fs";
import { io } from "socket.io-client";

const socket = io("https://example.com", {
  ca: readFileSync("./cert.pem")
});

サーバー

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./cert.pem"),
  key: readFileSync("./key.pem")
});
const io = new Server(httpServer);

クライアント証明書認証を使用した例

クライアント

import { readFileSync } from "fs";
import { io } from "socket.io-client";

const socket = io("https://example.com", {
  ca: readFileSync("./server-cert.pem"),
  cert: readFileSync("./client-cert.pem"),
  key: readFileSync("./client-key.pem"),
});

サーバー

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./server-cert.pem"),
  key: readFileSync("./server-key.pem"),
  requestCert: true,
  ca: [
    readFileSync("client-cert.pem")
  ]
});
const io = new Server(httpServer);

警告

rejectUnauthorizedはNode.js専用のオプションであり、ブラウザのセキュリティチェックをバイパスしません。

Security warning in the browser

マネージャーオプション

情報

これらの設定は、同じManagerに接続されているすべてのSocketインスタンスで共有されます。

`autoConnect`

デフォルト値: true

作成時に自動的に接続するかどうか。falseに設定されている場合、手動で接続する必要があります。

import { io } from "socket.io-client";

const socket = io({
  autoConnect: false
});

socket.connect();
// or
socket.io.open();

`parser`

v2.2.0で追加

デフォルト値：require("socket.io-parser")

パケットをマーシャリング/アンマーシャリングするために使用されるパーサー。詳細についてはこちらを参照してください。

`randomizationFactor`

デフォルト値：0.5

再接続時に使用されるランダム化係数（たとえば、サーバークラッシュ後にクライアントがまったく同時に再接続しないようにするため）。

デフォルト値を使用した例

最初の再接続試行は500〜1500msの間に行われます（1000 * 2^0 * (<-0.5から1.5の間の何か>)）
2回目の再接続試行は1000〜3000msの間に行われます（1000 * 2^1 * (<-0.5から1.5の間の何か>)）
3回目の再接続試行は2000〜5000msの間に行われます（1000 * 2^2 * (<-0.5から1.5の間の何か>)）
それ以降の再接続試行は5000ms後に行われます。

`reconnection`

デフォルト値: true

再接続が有効かどうか。falseに設定されている場合、手動で再接続する必要があります。

import { io } from "socket.io-client";

const socket = io({
  reconnection: false
});

const tryReconnect = () => {
  setTimeout(() => {
    socket.io.open((err) => {
      if (err) {
        tryReconnect();
      }
    });
  }, 2000);
}

socket.io.on("close", tryReconnect);

`reconnectionAttempts`

デフォルト値：Infinity

諦める前の再接続試行回数。

`reconnectionDelay`

デフォルト値：1000

ミリ秒単位での最初の再接続前の遅延（randomizationFactor値の影響を受けます）。

`reconnectionDelayMax`

デフォルト値：5000

2回の再接続試行間の最大遅延。各試行で再接続遅延が2倍になります。

`timeout`

デフォルト値：20000

各接続試行のタイムアウト（ミリ秒）。

ソケットオプション

情報

これらの設定は、指定されたSocketインスタンスに固有です。

`ackTimeout`

v4.6.0で追加

デフォルト値: -

確認応答を待機する際のデフォルトのタイムアウト（ミリ秒）（接続中にマネージャーによって使用される既存のtimeoutオプションと混同しないでください）。

`auth`

v3.0.0で追加

デフォルト値: -

名前空間へのアクセス時に送信される資格情報（こちらも参照）。

例

クライアント

import { io } from "socket.io-client";

const socket = io({
  auth: {
    token: "abcd"
  }
});

// or with a function
const socket = io({
  auth: (cb) => {
    cb({ token: localStorage.token })
  }
});

サーバー

io.on("connection", (socket) => {
  console.log(socket.handshake.auth); // prints { token: "abcd" }
});

名前空間へのアクセスが拒否された場合、authマップを更新できます。

socket.on("connect_error", (err) => {
  if (err.message === "invalid credentials") {
    socket.auth.token = "efgh";
    socket.connect();
  }
});

または、Socketインスタンスを手動で再接続させることができます。

socket.auth.token = "efgh";
socket.disconnect().connect();

`retries`

v4.6.0で追加

デフォルト値: -

最大再試行回数。制限を超えると、パケットは破棄されます。

const socket = io({
  retries: 3,
  ackTimeout: 10000
});

// implicit ack
socket.emit("my-event");

// explicit ack
socket.emit("my-event", (err, val) => { /* ... */ });

// custom timeout (in that case the ackTimeout is optional)
socket.timeout(5000).emit("my-event", (err, val) => { /* ... */ });

IOファクトリオプション​

forceNew​

multiplex​

低レベルエンジンオプション​

addTrailingSlash​

autoUnref​

closeOnBeforeunload​

extraHeaders​

forceBase64​

path​

protocols​

query​

rememberUpgrade​

timestampParam​

timestampRequests​

transportOptions​

transports​

upgrade​

withCredentials​

Node.js固有のオプション​

マネージャーオプション​

autoConnect​

parser​

randomizationFactor​

reconnection​

reconnectionAttempts​

reconnectionDelay​

reconnectionDelayMax​

timeout​

ソケットオプション​

ackTimeout​

auth​

retries​

IOファクトリオプション

`forceNew`

`multiplex`

低レベルエンジンオプション

`addTrailingSlash`

`autoUnref`

`closeOnBeforeunload`

`extraHeaders`

`forceBase64`

`path`

`protocols`

`query`

`rememberUpgrade`

`timestampParam`

`timestampRequests`

`transportOptions`

`transports`

`upgrade`

`withCredentials`

Node.js固有のオプション

マネージャーオプション

`autoConnect`

`parser`

`randomizationFactor`

`reconnection`

`reconnectionAttempts`

`reconnectionDelay`

`reconnectionDelayMax`

`timeout`

ソケットオプション

`ackTimeout`

`auth`

`retries`