Server SDK 참조

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

사용 가능한 SDK

언어	패키지	저장소
Node.js	@onesignal/node-onesignal	GitHub
Python	onesignal-python-api	GitHub
Java	onesignal-java-client	GitHub
Go	onesignal-go-api	GitHub
PHP	onesignal/onesignal-php-api	GitHub
Ruby	onesignal	GitHub
C# (.NET)	OneSignalApi	GitHub
Rust	onesignal-rust-api	GitHub

설치

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

npm install @onesignal/node-onesignal

pip install onesignal-python-api

Maven

<dependency>
  <groupId>com.onesignal</groupId>
  <artifactId>onesignal-java-client</artifactId>
  <version>5.3.0</version>
</dependency>

Gradle

implementation "com.onesignal:onesignal-java-client:5.3.0"

go get github.com/OneSignal/onesignal-go-api/v5

composer.json에 추가：

{
  "require": {
    "onesignal/onesignal-php-api": "^5.3"
  }
}

그런 다음 composer update를 실행하세요.

Gemfile에 추가：

gem 'onesignal', '~> 5.3'

그런 다음 bundle install을 실행하세요.

dotnet add package OneSignalApi

Cargo.toml의 [dependencies]에 추가：

onesignal-rust-api = "5.3.0"

구성

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

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

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);

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)

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);

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())

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
);

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

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);

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
}

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

푸시 알림 보내기

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

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);

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)

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());

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())

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();

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}"

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에 전달하기 전에 정규화하세요:

var normalizedContent = yourContent
   .Replace("\\r\\n", "\n")
   .Replace("\\n", "\n")
   .Replace("\r\n", "\n")
   .Replace("\r", "\n");

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;

이메일 보내기

email 채널로 구독에 이메일을 보냅니다.

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);

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)

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);

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()

$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);

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)

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);

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;

SMS 보내기

sms 채널로 구독에 SMS 문자 메시지를 보냅니다.

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);

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)

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);

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()

$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);

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)

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);

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;

전체 API 참조

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

SDK	API 참조
Node.js	DefaultApi.md
Python	DefaultApi.md
Java	DefaultApi.md
Go	DefaultApi.md
PHP	DefaultApi.md
Ruby	DefaultApi.md
C# (.NET)	DefaultApi.md
Rust	default_api docs

기본 REST API에 대해서는 전체 API 참조를 참조하세요.

FAQ

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

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

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

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

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

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

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

네. 모든 서버 SDK는 OpenAPI Generator를 사용하여 OneSignal OpenAPI 사양에서 생성됩니다. 이를 통해 모든 언어에서 일관된 API 적용 범위가 보장됩니다.

REST API 개요

엔드포인트, 인증, 속도 제한 및 요청/응답 형식.

키 및 ID

App ID, REST API 키 및 Organization API 키를 확인하세요.

트랜잭션 메시지

개인화된 데이터로 API를 통해 OTP, 영수증 및 시간에 민감한 알림을 보냅니다.

신원 확인

서버에서 생성된 JWT로 사용자 사칭을 방지하여 통합을 보호하세요.

Using the REST APIs

API reference

SDKs

사용 가능한 SDK

설치

구성

푸시 알림 보내기

이메일 보내기

SMS 보내기

전체 API 참조

FAQ

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

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

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

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

관련 페이지

REST API 개요

키 및 ID

트랜잭션 메시지

신원 확인

​사용 가능한 SDK

​설치

​구성

​푸시 알림 보내기

​이메일 보내기

​SMS 보내기

​전체 API 참조

​FAQ

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

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

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

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

​관련 페이지

REST API 개요

키 및 ID

트랜잭션 메시지

신원 확인

사용 가능한 SDK

설치

구성

푸시 알림 보내기

이메일 보내기

SMS 보내기

전체 API 참조

FAQ

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

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

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

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

관련 페이지