# 클라이언트 초기화

## Content

`js-collaboration-client`는 서버와의 양방향 통신을 설정하기 위한 강력한 클라이언트 측 라이브러리를 제공합니다. 이 가이드는 다음 내용을 다룹니다.

* 동시 작업 클라이언트 생성
* 서버 룸에 연결

## 클라이언트 생성

1. npm 패키지 설치

    ```bash
    npm install @mescius/js-collaboration-client
    ```
2. 클라이언트 인스턴스 생성
<br>
    [Client](/spreadjs/api/v19/collaboration/js-collaboration-client/classes/Client) 클래스를 사용하여 클라이언트 인스턴스를 생성할 수 있으며, 필요에 따라 서버 URL을 지정할 수 있습니다. 동시 작업 서비스가 프론트엔드와 동일한 도메인에서 호스팅되는 경우, 다음과 같이 간단히 사용할 수 있습니다.

    ```typescript
    import { Client } from "@mescius/js-collaboration-client";
    const client = new Client(); // 서버 URL은 window.location 객체를 기반으로 자동 추론됨
    ```

    크로스 도메인 환경에서는 서버 URL을 명시적으로 지정해야 합니다.

    ```typescript
    const client = new Client("ws://server-domain.com:8000");
    ```

## 서버에 연결하고 룸에 참여하기

* 기본 연결
    다음 코드를 사용하여 서버에 [연결](/spreadjs/api/v19/collaboration/js-collaboration-client/classes/Client#connect)하고 지정된 룸에 참여할 수 있습니다.

    ```typescript
    const connection = client.connect('roomId');
    ```
* 추가 정보와 함께 연결
    연결을 설정하는 동안 추가 정보(예: 사용자 인증 정보)를 포함하려면 `query` 및 `auth` [파라미터](/spreadjs/api/v19/collaboration/js-collaboration-client/interfaces/IConnectOptions#interface-iconnectoptions)를 전달할 수 있습니다. 이 정보는 서버 측 `connect` 미들웨어에서 접근하여 사용할 수 있습니다.

    ```typescript
    const connection = client.connect('roomId', {
        query: {
            myQueryArg: 'xxx',  // 서버 측에서 context.connection.query로 접근 가능
        },
        auth: {
            token: 'xxx'  // 서버 측에서 context.connection.auth.token으로 접근 가능
        }
    });
    ```

    실제 활용 예로는 사용자 인증 정보(예: 토큰)를 `auth` 파라미터로 서버에 전달하는 경우가 있습니다. 서버는 미들웨어를 통해 이 인증 정보를 조회하고 검증하여 사용자의 연결 허용 여부를 결정할 수 있습니다.
    사용자 인증 및 권한에 대한 자세한 내용은 [사용자 인증 및 권한](/spreadjs/docs/v19/spreadjs-collaboration-server/collaboration-framework/js-collaboration/user-authentication-and-permissions)을 참고하세요.

## 다음 단계

[Client](/spreadjs/api/v19/collaboration/js-collaboration-client/classes/Client) 클래스는 서버에 연결하기 위한 첫 단계입니다. 간단한 초기화와 [connect](/spreadjs/api/v19/collaboration/js-collaboration-client/classes/Client#connect) 호출만으로 동시 작업 룸에 빠르게 참여할 수 있습니다.
연결이 성공하면 반환되는 `Connection` 객체를 사용하여 양방향 통신과 이벤트 관리를 구현할 수 있습니다.
자세한 내용은 [Connection Class](/spreadjs/docs/v19/spreadjs-collaboration-server/collaboration-framework/js-collaboration/connection-class)를 참고하세요.