서버 참조

서버 구현은 선택사항입니다. 다음 작업을 수행하려면 인스턴스 ID 서비스를 사용하세요.

앱 인스턴스에 대한 정보 가져오기

앱 인스턴스에 대한 정보를 가져오려면 이 엔드포인트에서 인스턴스 ID 서비스를 호출하여 다음과 같이 앱 인스턴스의 토큰을 제공합니다.

 https://iid.googleapis.com/iid/info/IID_TOKEN

매개변수

  • Authorization: key=YOUR_API_KEY입니다. 헤더에서 이 매개변수를 설정하세요.
  • [선택사항] 부울 details: 이 쿼리 매개변수를 true로 설정하여 이 토큰과 연결된 FCM 또는 GCM 주제 구독 정보 (있는 경우)를 가져옵니다. 지정하지 않으면 기본값은 false입니다.

결과

성공하면 HTTP 상태 200과 다음 항목이 포함된 JSON 객체가 반환됩니다.

  • application - 토큰과 연결된 패키지 이름입니다.
  • authorizedEntity - 토큰으로 전송하도록 승인된 projectId입니다.
  • applicationVersion - 애플리케이션의 버전입니다.
  • 패키지에 적용된 서명의 appSigner - sha1 지문입니다. 앱에 서명한 당사자를 나타냅니다(예: Play Store).
  • platform - ANDROID, IOS, CHROME를 반환하여 토큰이 속한 기기 플랫폼을 나타냅니다.

details 플래그가 설정된 경우:

  • rel - 토큰과 연결된 관계입니다. 주제 구독 목록을 예로 들 수 있습니다.

GET 요청 예시

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

결과 예

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

앱 인스턴스의 관계 맵 만들기

Instance ID API를 사용하면 앱 인스턴스의 관계 맵을 만들 수 있습니다. 예를 들어 등록 토큰을 Google 클라우드 메시징 주제에 매핑하여 앱 인스턴스에서 이 주제를 구독할 수 있습니다. API는 이러한 관계를 개별적으로 그리고 일괄적으로 만드는 메서드를 제공합니다.

앱 인스턴스의 관계 매핑 만들기

등록 토큰과 지원되는 관계가 있으면 매핑을 만들 수 있습니다. 예를 들어 이 엔드포인트에서 인스턴스 ID 서비스를 호출하여 다음과 같이 앱 인스턴스의 토큰을 제공하여 Google 클라우드 메시징 주제를 구독하도록 앱 인스턴스를 구독할 수 있습니다.

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

매개변수

  • Authorization: key=YOUR_API_KEY입니다. 헤더에서 이 매개변수를 설정하세요.

결과

성공하면 호출에서 HTTP 상태 200을 반환합니다.

POST 요청 예시

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

결과 예

HTTP 200 OK
{}

여러 앱 인스턴스의 관계 매핑 관리

인스턴스 ID 서비스의 일괄 메서드를 사용하면 앱 인스턴스의 일괄 관리를 수행할 수 있습니다. 예를 들어 FCM 또는 GCM 주제에 앱 인스턴스를 일괄 추가하거나 삭제할 수 있습니다. API 호출당 최대 1,000개의 앱 인스턴스를 업데이트하려면 이 엔드포인트에서 인스턴스 ID 서비스를 호출하여 JSON 본문에 앱 인스턴스 토큰을 제공합니다.

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

매개변수

  • Authorization: key=YOUR_API_KEY입니다. 헤더에서 이 매개변수를 설정하세요.
  • to: 주제 이름입니다.
  • registration_tokens : 추가 또는 삭제하려는 앱 인스턴스의 IID 토큰 배열입니다.

결과

성공하면 호출에서 HTTP 상태 200을 반환합니다. 빈 결과는 토큰 구독의 성공 여부를 나타냅니다. 실패한 구독의 경우 결과에 다음 오류 코드 중 하나가 포함됩니다.

  • NOT_FOUND — 등록 토큰이 삭제되었거나 앱이 제거되었습니다.
  • INVALID_ARGUMENT — 제공된 등록 토큰이 발신자 ID에 유효하지 않습니다.
  • 내부용 — 알 수 없는 이유로 백엔드 서버가 실패했습니다. 요청을 다시 시도하세요.
  • TOO_MANY_TOPICS — 앱 인스턴스당 주제가 너무 많습니다.

POST 요청 예시

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

결과 예

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

APN 토큰의 등록 토큰 만들기

인스턴스 ID 서비스의 batchImport 메서드를 사용하여 기존 iOS APN 토큰을 Google 클라우드 메시징 또는 Firebase 클라우드 메시징으로 일괄 가져와 유효한 등록 토큰에 매핑할 수 있습니다. 이 엔드포인트에서 인스턴스 ID 서비스를 호출하여 JSON 본문에 APN 토큰 목록을 제공합니다.

 https://iid.googleapis.com/iid/v1:batchImport

응답 본문에는 FCM 또는 GCM 메시지를 해당 APN 기기 토큰으로 전송하는 데 사용할 수 있는 인스턴스 ID 등록 토큰의 배열이 포함됩니다.

매개변수

  • Authorization: key=YOUR_API_KEY입니다. 헤더에서 이 매개변수를 설정하세요.
  • application : 앱의 번들 ID입니다.
  • sandbox: 샌드박스 환경 (TRUE) 또는 프로덕션 (FALSE)을 나타내는 불리언
  • apns_tokens: 추가하거나 삭제하려는 앱 인스턴스의 APN 토큰 배열입니다. 요청당 최대 100개의 토큰입니다.

결과

성공하면 호출에서 HTTP 상태 200과 JSON 결과 본문을 반환합니다. 요청에 제공된 각 APN 토큰에 대해 결과 목록에는 다음이 포함됩니다.

  • APN 토큰입니다.
  • 상태를 나타냅니다. OK 또는 실패를 설명하는 오류 메시지
  • 성공적인 결과를 얻으려면 FCM 또는 GCM이 APN 토큰에 매핑하는 등록 토큰입니다.

POST 요청 예시

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

결과 예

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

푸시 구독 등록 토큰 관리

인스턴스 ID 서비스의 웹 메서드를 사용하면 Firebase 클라우드 메시징의 기존 푸시 구독을 가져올 수 있습니다. 업데이트 및 삭제도 가능합니다.

푸시 구독을 가져오면 등록 토큰이 생성됩니다. 이 토큰을 사용하면 주제 메시징 및 기기 그룹 메시징과 같은 FCM 기능을 사용하여 웹 앱에 알림을 타겟팅할 수 있습니다.

푸시 구독 가져오기

InstanceID의 웹 엔드포인트를 사용하여 푸시 구독을 가져올 수 있습니다.

 https://iid.googleapis.com/v1/web/iid

요청에는 OAuth 2.0 액세스 토큰으로 설정된 승인 헤더, 애플리케이션 서버 키로 설정된 암호화 키 헤더, 요청 본문의 PushSubscription 객체가 포함되어야 합니다.

응답 본문에는 페이로드를 암호화할 필요 없이 FCM 또는 GCM 메시지를 해당 웹 앱 인스턴스로 전송하는 데 사용할 수 있는 등록 토큰이 포함됩니다.

콘솔에 VAPID 키 쌍 업로드

키를 가져오려면 Firebase 프로젝트에 액세스할 수 있는 소유자 수준의 권한이 있어야 합니다. 기존 공개 및 비공개 키를 base64 URL 보안 인코딩 양식으로 가져옵니다.

  1. Firebase Console 설정 창의 클라우드 메시징 탭을 열고 웹 구성 섹션으로 스크롤합니다.
  2. 웹 푸시 인증서 탭에서 링크 텍스트인 "기존 키 쌍을 가져옵니다."를 찾아서 선택합니다.
  3. 키 쌍 가져오기 대화상자에서 해당 필드에 공개 및 비공개 키를 입력하고 가져오기를 클릭합니다. 콘솔에 공개 키 문자열과 추가된 날짜가 표시됩니다.

OAuth2 토큰 검색: 사용자 인증 정보를 사용하여 액세스 토큰 발급

요청에 대한 액세스 토큰을 생성하려면 액세스 토큰을 발급하여 HTTP 요청에 추가해야 합니다.

node.js

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

자바

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

FCM에 대한 액세스를 승인하려면 https://www.googleapis.com/auth/firebase.messaging 범위를 요청합니다.

매개변수

  • 승인: Bearer <access_token> 헤더에서 이 매개변수를 설정하세요.
  • 암호화 키: p256ecdsa=APPLICATION_PUBLIC_KEY. 헤더에서 이 매개변수를 설정하세요.
  • 요청 본문: PushSubscription.toJson() 푸시 본문을 파싱하지 않고 HTTP 본문에 전달합니다. 콘텐츠가 PushSubscription의 W3C 인코딩과 일치합니다.

응답

성공하면 HTTP 상태 200 OK와 IID 토큰이 포함된 JSON 결과 본문이 반환됩니다.

POST 요청 예시

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

결과 예

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

푸시 구독 업데이트

다음 엔드포인트를 사용하여 등록 토큰과 연결된 푸시 구독을 업데이트할 수 있습니다.

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

매개변수

  • 승인: Bearer <access_token> 헤더에서 이 매개변수를 설정하세요.
  • 암호화 키: p256ecdsa=APPLICATION_PUBLIC_KEY. 헤더에서 이 매개변수를 설정하세요.
  • 요청 본문: PushSubscription.toJson() 푸시 구독을 파싱하지 않고 HTTP 본문에 전달합니다. 콘텐츠가 PushSubscription의 W3C 인코딩과 일치합니다.

결과

성공하면 HTTP 상태 200 및 등록 토큰이 반환됩니다. 요청에서 전달한 것과 동일한 토큰이거나 새 토큰일 수 있습니다.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

POST 요청 예시

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

결과 예

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

푸시 구독 삭제

DELETE 요청은 FCM 데이터베이스에서 푸시 구독 세부정보를 삭제합니다. Push API 프로토콜을 사용하여 웹 애플리케이션에서 메시지를 계속 수신할 수 있습니다.

푸시 구독을 삭제하려면 다음 주소로 DELETE 요청을 보내세요.

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

DELETE 요청 예시

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

결과 예

 HTTP 200 OK {}

오류 응답

Instance ID server API를 호출하면 다음 HTTP 오류 코드가 반환됩니다.

  • HTTP status 400 (Bad request) - 요청 매개변수가 누락되었거나 잘못되었습니다. 자세한 내용은 오류 메시지를 확인하세요.
  • HTTP status 401 (Unauthorized) - 승인 헤더가 잘못되었습니다.
  • HTTP status 403 (Forbidden) - 승인 헤더가 authorizedEntity와 일치하지 않습니다.
  • HTTP status 404 (Not found) - 잘못된 HTTP 경로 또는 IID 토큰을 찾을 수 없습니다. 자세한 내용은 오류 메시지를 확인하세요.
  • HTTP status 503 (Service unavailable) - 서비스를 사용할 수 없습니다. 지수 백오프로 요청을 다시 시도하세요.