# 시작하기

앱의 인증 토큰과 사용자 ID를 준비해 Context API를 호출하고, 응답과 서비스 동작을 확인하는 방법을 안내합니다.

Source: https://cue.airbridge.io/docs/ko/quickstart
Language: ko
Updated: 2026-10-15

에어브릿지 CUE를 연동하려면 앱의 인증 토큰과 사용자 ID가 필요합니다. 마케터는 개인화할 화면이나 메시지와 적용 조건을 정하고, 개발자는 Context API의 응답에 따라 앱이나 CRM이 작동하도록 구현합니다.

## 시작하기 전에 필요한 준비물

대상 앱의 CUE 사용 설정과 예측 데이터 준비 여부는 에어브릿지 담당자에게 확인해 주세요.

### 인증 토큰 준비하기

Context API 인증에는 대상 앱의 앱 SDK 토큰이나 웹 SDK 토큰을 사용합니다. 토큰은 에어브릿지 대시보드 \[설정]>\[토큰 관리]에서 확인할 수 있습니다. 자세한 내용은 [토큰 관리 가이드](https://help.airbridge.io/ko/guides/tokens)에서 안내합니다.

준비한 토큰은 서버나 CRM의 안전한 설정에 보관해야 합니다.

### 사용자 ID 선택하기

Context API 요청에는 아래 3개 필드 중 반드시 하나만 넣어야 합니다. 토큰과 같은 앱에서 수집한 ID를 사용해야 하며, 값은 비어 있지 않은 문자열이어야 합니다.

| 요청 필드                 | ID의 종류                                                           |
| ------------------------- | ------------------------------------------------------------------- |
| `userId`                  | 에어브릿지가 부여한 사용자 식별자인 Airbridge Generated UUID입니다. |
| `brazeDeviceId`           | 브레이즈 SDK의 Device ID입니다.                                     |
| `airbridgeExternalUserId` | 서비스에서 에어브릿지에 전송한 외부 사용자 ID입니다.                |

`brazeDeviceId`는 브레이즈의 `external_id`와 다른 값입니다.

### 사용자 ID 연결하기

Context API에서 사용할 ID는 조회할 사용자와 연결되어 있어야 합니다. ID를 SDK에서 조회하는 방법과 브레이즈 및 외부 사용자 ID를 연결하는 방법은 [이벤트 연동 확인하기의 사용자 ID 연결](/docs/ko/event-integration#사용자-id-연결)에서 안내합니다.

### 테스트 요청 준비하기

ID 연결을 마친 테스트 사용자와 기기를 정하고, 앱을 실행해 요청에 사용할 ID를 준비해 주세요. [첫 요청 보내기](#첫-요청-보내기)의 요청 본문에 선택한 ID 필드 하나를 넣고 대상 앱의 토큰으로 요청하면 됩니다. 결과는 [응답 확인하기](#응답-확인하기)에서 확인할 수 있습니다.

## 활용 목적 정하기

API 응답을 서비스에 적용하려면 개인화할 화면이나 메시지, 적용할 조건과 기본 동작을 정해야 합니다.

* 개인화할 화면이나 메시지를 정해 주세요. 예를 들어 구매 가능성이 높은 사용자에게 첫 화면에서 안내할 상품을 다르게 정할 수 있습니다.
* 해당 조건에 사용할 예측값을 정해 주세요. 구매와 이탈은 서로 다른 사건을 예측하므로 활용 목적에 맞게 선택해야 합니다.
* 조건을 충족하지 않거나 API 응답을 받지 못했을 때 제공할 기본 화면이나 메시지도 정해야 합니다.

## 첫 요청 보내기

아래는 외부 사용자 ID로 조회하는 요청입니다. `abc-123`을 대상 앱에서 에어브릿지에 전송한 외부 사용자 ID로 바꿔 주세요. 서버나 CRM에서 요청을 보내 주세요.

cURL

서버의 환경 변수 `AIRBRIDGE_APP_TOKEN`에 준비한 토큰을 설정한 뒤 아래 명령을 실행해 주세요. 응답 헤더와 JSON 본문을 함께 확인할 수 있습니다.

```bash
curl --request POST --include \
  'https://api.airbridge.io/entry/inference/v1/context' \
  --header "Authorization: Bearer ${AIRBRIDGE_APP_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"airbridgeExternalUserId":"abc-123"}'
```

HTTP

`<AIRBRIDGE_APP_TOKEN>`을 준비한 토큰으로 바꿔 주세요.

```http
POST /entry/inference/v1/context HTTP/1.1
Host: api.airbridge.io
Authorization: Bearer <AIRBRIDGE_APP_TOKEN>
Content-Type: application/json

{
  "airbridgeExternalUserId": "abc-123"
}
```

다른 종류의 ID를 사용하려면 [Context API의 Payload 예시](/docs/ko/reference/context-api#payload-예시)에서 요청 형식을 확인할 수 있습니다. 요청 본문에는 선택한 ID 필드 하나만 넣어야 합니다.

## 응답과 서비스 동작 확인하기

첫 요청을 보낸 뒤에는 API 응답이 올바른지 확인하고, 서비스가 응답에 따라 의도대로 작동하는지 테스트해야 합니다.

### 응답 확인하기

요청이 정상적으로 처리되면 HTTP `200` 응답을 받습니다. 아래는 예시입니다.

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a

{
  "requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a",
  "appId": 1234,
  "user": {
    "id": "abc-123",
    "type": "airbridge_external_user_id"
  },
  "context": {
    "lastTouchpoint": {
      "channel": "media_A",
      "campaign": "moving_service",
      "adGroup": "moving_quote",
      "adCreative": "moving_guide_video",
      "term": null
    }
  },
  "predictions": {
    "d3_purchase": {
      "probability": 0.723,
      "tier": "high"
    },
    "d3_churn": {
      "probability": 0.812,
      "tier": "high"
    }
  }
}
```

* \[ ] 예측 데이터가 준비된 테스트 사용자로 HTTP `200` 응답을 받았는지 확인해 주세요.
* \[ ] `appId`가 대상 앱을 가리키고, `user.id`와 `user.type`이 요청에 사용한 ID의 값과 종류를 나타내는지 확인해 주세요.
* \[ ] `context.lastTouchpoint`에서 필요한 광고 기여 정보를 읽고, 테스트에서 예상한 기여 결과와 일치하는지 확인해 주세요.
* \[ ] `predictions.d3_purchase`와 `predictions.d3_churn`의 `probability`와 `tier`를 의도한 조건에 적용하는지 확인해 주세요.

### 서비스 동작 확인하기

* \[ ] 조건을 충족할 때와 충족하지 않을 때 각각 정한 화면이나 메시지가 나타나는지 확인해 주세요.
* \[ ] 설치 유입 정보를 사용하는 규칙에서 `context.lastTouchpoint` 객체나 필요한 필드가 `null`일 때 미리 정한 기본 규칙을 적용하는지 확인해 주세요.
* \[ ] API 오류, 시간 초과, 읽을 수 없는 응답이 발생했을 때도 기본 동작을 유지하는지 확인해 주세요.

예측 결과를 받지 못하면 기본 동작을 유지해야 합니다. 오류를 확률 `0`이나 등급 `low`로 바꾸면 정보가 없는 상태를 낮은 가능성으로 잘못 해석하게 됩니다. 상황별 처리 방법은 [오류 처리](/docs/ko/reference/errors)에서 확인할 수 있습니다.

## 연동 문제 문의하기

에어브릿지 담당자에게 문의할 때는 호출 시각, `requestId`, HTTP 상태 코드와 `error.code`를 함께 전달해 주세요. `requestId`를 받지 못했다면 호출한 URL과 메서드, 발생 상황을 알려 주세요.

첫 연동을 확인한 다음에는 [이벤트 연동 확인하기](/docs/ko/event-integration)에서 기존 이벤트의 수집 상태를 점검하고, [Context 활용하기](/docs/ko/guides/using-context)에서 개인화 규칙과 기본 동작을 구체화할 수 있습니다.