> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server SDK 참조

> Node.js, Python, Java, Go, PHP, Ruby, C#, Rust 백엔드에서 푸시 알림, 이메일, SMS를 보내기 위해 OneSignal 서버 SDK를 설치, 구성 및 사용합니다.

모든 OneSignal 서버 SDK는 동일한 OpenAPI 사양에서 생성되므로 언어에 관계없이 일관된 인터페이스를 공유합니다. 각 SDK는 [OneSignal REST API](/reference/create-message)를 래핑하고 요청 및 응답에 대한 타입이 지정된 모델을 제공합니다.

## 사용 가능한 SDK

| 언어        | 패키지                                                                                                | 저장소                                                         |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## 설치

<Note>
  아래 버전 번호는 예시입니다. 최신 버전을 설치하려면 각 SDK의 패키지 레지스트리를 확인하세요.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    `composer.json`에 추가：

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    그런 다음 `composer update`를 실행하세요.
  </Tab>

  <Tab title="Ruby">
    `Gemfile`에 추가：

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    그런 다음 `bundle install`을 실행하세요.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    `Cargo.toml`의 `[dependencies]`에 추가：

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## 구성

모든 SDK는 API 키를 통한 인증이 필요합니다. 두 가지 키 유형을 사용할 수 있습니다：

* **REST API 키** — 알림 전송, 사용자 관리 등 대부분의 엔드포인트에 필요합니다. 앱의 **설정 > 키 및 ID**에서 찾을 수 있습니다.
* **Organization API 키** — 앱 생성 또는 목록 조회와 같은 조직 수준 엔드포인트에만 필요합니다. **Organization 설정**에서 찾을 수 있습니다.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const OneSignal = require('@onesignal/node-onesignal');

    const configuration = OneSignal.createConfiguration({
      restApiKey: 'YOUR_REST_API_KEY',
      organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
    });

    const client = new OneSignal.DefaultApi(configuration);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import onesignal
    from onesignal.api import default_api

    configuration = onesignal.Configuration(
        rest_api_key='YOUR_REST_API_KEY',
        organization_api_key='YOUR_ORGANIZATION_API_KEY',
    )

    with onesignal.ApiClient(configuration) as api_client:
        client = default_api.DefaultApi(api_client)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.ApiClient;
    import com.onesignal.client.Configuration;
    import com.onesignal.client.auth.HttpBearerAuth;
    import com.onesignal.client.api.DefaultApi;

    ApiClient defaultClient = Configuration.getDefaultApiClient();

    HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("rest_api_key");
    restApiAuth.setBearerToken("YOUR_REST_API_KEY");

    HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
        .getAuthentication("organization_api_key");
    orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

    DefaultApi client = new DefaultApi(defaultClient);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import onesignal "github.com/OneSignal/onesignal-go-api"

    restAuth := context.WithValue(
        context.Background(),
        onesignal.RestApiKey,
        "YOUR_REST_API_KEY",
    )

    orgAuth := context.WithValue(
        restAuth,
        onesignal.OrganizationApiKey,
        "YOUR_ORGANIZATION_API_KEY",
    )

    apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\api\DefaultApi;
    use onesignal\client\Configuration;
    use GuzzleHttp;

    $config = Configuration::getDefaultConfiguration()
        ->setRestApiKeyToken('YOUR_REST_API_KEY')
        ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

    $client = new DefaultApi(
        new GuzzleHttp\Client(),
        $config
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'onesignal'

    OneSignal.configure do |config|
      config.rest_api_key = 'YOUR_REST_API_KEY'
      config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
    end

    client = OneSignal::DefaultApi.new
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Api;
    using OneSignalApi.Client;

    var config = new Configuration();
    config.BasePath = "https://api.onesignal.com";
    config.AccessToken = "YOUR_REST_API_KEY";

    var client = new DefaultApi(config);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::configuration::Configuration;

    fn create_configuration() -> Configuration {
        let mut config = Configuration::new();
        config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
        config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
        config
    }
    ```
  </Tab>
</Tabs>

<Warning>
  API 키를 환경 변수 또는 시크릿 매니저에 저장하세요. 소스 컨트롤에 커밋하지 마세요.
</Warning>

***

## 푸시 알림 보내기

세그먼트를 타겟팅하여 웹 및 모바일 [구독](./subscriptions)에 푸시 알림을 보냅니다. 이 예시들은 정상 경로를 보여줍니다 — 프로덕션 사용을 위해 오류 처리(try/catch, 오류 콜백)를 추가하세요.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Hello from OneSignal!' };
    notification.headings = { en: 'Push Notification' };
    notification.included_segments = ['Subscribed Users'];

    const response = await client.createNotification(notification);
    console.log('Notification ID:', response.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Hello from OneSignal!'),
        headings=onesignal.StringMap(en='Push Notification'),
        included_segments=['Subscribed Users'],
    )

    response = client.create_notification(notification)
    print('Notification ID:', response.id)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.onesignal.client.model.Notification;
    import com.onesignal.client.model.StringMap;

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");

    StringMap contents = new StringMap();
    contents.en("Hello from OneSignal!");
    notification.setContents(contents);

    StringMap headings = new StringMap();
    headings.en("Push Notification");
    notification.setHeadings(headings);

    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

    var response = client.createNotification(notification);
    System.out.println("Notification ID: " + response.getId());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
    notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()

    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Notification ID:", response.GetId())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use onesignal\client\model\Notification;
    use onesignal\client\model\StringMap;

    $content = new StringMap();
    $content->setEn('Hello from OneSignal!');

    $headings = new StringMap();
    $headings->setEn('Push Notification');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setHeadings($headings);
    $notification->setIncludedSegments(['Subscribed Users']);

    $response = $client->createNotification($notification);
    echo 'Notification ID: ' . $response->getId();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Hello from OneSignal!' },
      headings: { en: 'Push Notification' },
      included_segments: ['Subscribed Users']
    })

    response = client.create_notification(notification)
    puts "Notification ID: #{response.id}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    using OneSignalApi.Model;

    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Hello from OneSignal!"),
        Headings = new StringMap(en: "Push Notification"),
        IncludedSegments = new List<string> { "Subscribed Users" }
    };

    var response = client.CreateNotification(notification);
    Console.WriteLine("Notification ID: " + response.Id);
    ```

    참고: .NET SDK는 줄바꿈 문자를 자동으로 정규화하지 않습니다. 콘텐츠에 `\r\n`이 포함된 경우 `Contents`에 전달하기 전에 정규화하세요:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use onesignal::apis::default_api;
    use onesignal::models::{Notification, StringMap};

    let mut contents = StringMap::new();
    contents.en = Some("Hello from OneSignal!".to_string());

    let mut headings = StringMap::new();
    headings.en = Some("Push Notification".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.headings = Some(Box::new(headings));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

    let config = create_configuration();
    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## 이메일 보내기

`email` 채널로 [구독](./subscriptions)에 이메일을 보냅니다.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.email_subject = 'Important Update';
    notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'email';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        email_subject='Important Update',
        email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='email',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setEmailSubject("Important Update");
    notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("email");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetEmailSubject("Important Update")
    notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("email")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setEmailSubject('Important Update');
    $notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('email');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      email_subject: 'Important Update',
      email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'email'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        EmailSubject = "Important Update",
        EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "email"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.email_subject = Some("Important Update".to_string());
    notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("email".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## SMS 보내기

`sms` 채널로 [구독](./subscriptions)에 SMS 문자 메시지를 보냅니다.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const notification = new OneSignal.Notification();
    notification.app_id = 'YOUR_APP_ID';
    notification.contents = { en: 'Your SMS message content here' };
    notification.included_segments = ['Subscribed Users'];
    notification.channel_for_external_user_ids = 'sms';
    notification.sms_from = '+15551234567';

    const response = await client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    notification = onesignal.Notification(
        app_id='YOUR_APP_ID',
        contents=onesignal.StringMap(en='Your SMS message content here'),
        included_segments=['Subscribed Users'],
        channel_for_external_user_ids='sms',
        sms_from='+15551234567',
    )

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    StringMap contents = new StringMap();
    contents.en("Your SMS message content here");

    Notification notification = new Notification();
    notification.setAppId("YOUR_APP_ID");
    notification.setContents(contents);
    notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
    notification.setChannelForExternalUserIds("sms");
    notification.setSmsFrom("+15551234567");

    var response = client.createNotification(notification);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    notification := *onesignal.NewNotification("YOUR_APP_ID")
    notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
    notification.SetIncludedSegments([]string{"Subscribed Users"})
    notification.SetChannelForExternalUserIds("sms")
    notification.SetSmsFrom("+15551234567")

    response, _, err := apiClient.DefaultApi
        .CreateNotification(orgAuth)
        .Notification(notification)
        .Execute()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $content = new StringMap();
    $content->setEn('Your SMS message content here');

    $notification = new Notification();
    $notification->setAppId('YOUR_APP_ID');
    $notification->setContents($content);
    $notification->setIncludedSegments(['Subscribed Users']);
    $notification->setChannelForExternalUserIds('sms');
    $notification->setSmsFrom('+15551234567');

    $response = $client->createNotification($notification);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    notification = OneSignal::Notification.new({
      app_id: 'YOUR_APP_ID',
      contents: { en: 'Your SMS message content here' },
      included_segments: ['Subscribed Users'],
      channel_for_external_user_ids: 'sms',
      sms_from: '+15551234567'
    })

    response = client.create_notification(notification)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    var notification = new Notification(appId: "YOUR_APP_ID")
    {
        Contents = new StringMap(en: "Your SMS message content here"),
        IncludedSegments = new List<string> { "Subscribed Users" },
        ChannelForExternalUserIds = "sms",
        SmsFrom = "+15551234567"
    };

    var response = client.CreateNotification(notification);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let mut contents = StringMap::new();
    contents.en = Some("Your SMS message content here".to_string());

    let mut notification = Notification::new("YOUR_APP_ID".to_string());
    notification.contents = Some(Box::new(contents));
    notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
    notification.channel_for_external_user_ids = Some("sms".to_string());
    notification.sms_from = Some("+15551234567".to_string());

    let response = default_api::create_notification(&config, notification).await;
    ```
  </Tab>
</Tabs>

***

## 전체 API 참조

각 서버 SDK는 동일한 API 엔드포인트 세트를 지원합니다. 사용자, 구독, 세그먼트, 템플릿 등을 포함한 전체 메서드 목록은 SDK의 API 문서를 참조하세요.

| SDK       | API 참조                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------- |
| Node.js   | [DefaultApi.md](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

기본 REST API에 대해서는 [전체 API 참조](/reference/create-message)를 참조하세요.

***

## FAQ

### 어떤 서버 SDK를 선택해야 하나요?

백엔드 언어에 맞는 SDK를 사용하세요. 모든 서버 SDK는 동일한 OpenAPI 사양에서 생성되고 동일한 엔드포인트를 지원하므로 언어 간 기능이 동일합니다.

### REST API 키와 Organization API 키의 차이점은 무엇인가요?

**REST API 키**는 단일 앱으로 범위가 지정되며 알림 전송 및 사용자 관리와 같은 대부분의 작업에 필요합니다. **Organization API 키**는 조직으로 범위가 지정되며 앱 생성 또는 목록 조회에만 필요합니다. 대부분의 통합에는 REST API 키만 필요합니다.

### SDK 대신 REST API를 직접 사용할 수 있나요?

네. 서버 SDK는 [OneSignal REST API](/reference/create-message)를 편리하게 래핑한 것입니다. `key` 인증 스키마(`Authorization: key YOUR_REST_API_KEY`)를 사용하여 모든 HTTP 클라이언트로 API를 직접 호출할 수 있습니다.

### 이 SDK들은 자동 생성되나요?

네. 모든 서버 SDK는 [OpenAPI Generator](https://openapi-generator.tech)를 사용하여 OneSignal OpenAPI 사양에서 생성됩니다. 이를 통해 모든 언어에서 일관된 API 적용 범위가 보장됩니다.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="REST API 개요" icon="code" href="/reference/rest-api-overview">
    엔드포인트, 인증, 속도 제한 및 요청/응답 형식.
  </Card>

  <Card title="키 및 ID" icon="key" href="./keys-and-ids">
    App ID, REST API 키 및 Organization API 키를 확인하세요.
  </Card>

  <Card title="트랜잭션 메시지" icon="paper-plane" href="./transactional-messages">
    개인화된 데이터로 API를 통해 OTP, 영수증 및 시간에 민감한 알림을 보냅니다.
  </Card>

  <Card title="신원 확인" icon="shield-halved" href="./identity-verification">
    서버에서 생성된 JWT로 사용자 사칭을 방지하여 통합을 보호하세요.
  </Card>
</Columns>