# Context API

사용자 ID로 설치 유입 정보와 구매 및 이탈 예측값을 조회하는 요청과 응답 규격입니다.

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

Context API는 앱 사용자 ID를 받아 설치에 기여한 광고 정보와 구매 및 이탈 예측값을 반환합니다. 호출하려면 앱의 CUE 사용 설정과 예측 데이터가 준비돼 있어야 합니다. 연동을 테스트할 때는 예측 데이터가 준비된 테스트 사용자 ID를 사용해야 합니다. 자세한 준비 과정은 [시작하기](/docs/ko/quickstart)에서 확인할 수 있습니다.

## Endpoint

```text
POST https://api.airbridge.io/entry/inference/v1/context
```

서버나 CRM에서 API를 호출해 주세요. CUE는 인증 토큰으로 대상 앱을 확인합니다. 요청 본문에는 `appId`를 넣지 않아야 합니다.

## 요청

### 전체 요청

외부 사용자 ID로 조회하는 전체 요청입니다. 토큰과 사용자 ID를 실제 값으로 바꿔 주세요. 다른 ID를 사용하는 요청은 아래 [Payload 예시](#payload-예시)에서 확인할 수 있습니다.

HTTP

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

cURL

서버 환경 변수 `AIRBRIDGE_APP_TOKEN`에 토큰을 설정했다면 아래 cURL 예시를 사용할 수 있습니다. `abc-123`을 예측 데이터가 준비된 실제 테스트 사용자 ID로 바꿔 주세요.

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

### Headers

`Authorization` (`string`, 필수)

앱 SDK 토큰이나 웹 SDK 토큰을 `Bearer <AIRBRIDGE_APP_TOKEN>` 형식으로 보내 주세요.

`Content-Type` (`string`, 필수)

`application/json`을 보내 주세요.

토큰은 에어브릿지 대시보드 \[설정]>\[토큰 관리]에서 확인할 수 있습니다. 서버나 CRM의 안전한 설정에 보관해야 합니다. 자세한 내용은 [토큰 확인 방법](https://help.airbridge.io/ko/guides/tokens)에서 확인할 수 있습니다.

### Request body

사용자 식별자

(`object`)

이 그룹의 필드 중 정확히 하나를 포함해야 합니다.

`userId` (`string`)

에어브릿지가 앱 사용자에게 부여한 Airbridge Generated UUID를 보내 주세요.

`brazeDeviceId` (`string`)

브레이즈 SDK의 Device ID를 보내 주세요.

`airbridgeExternalUserId` (`string`)

서비스에서 에어브릿지에 전송한 외부 사용자 ID를 보내 주세요.

API는 ID의 앞뒤 공백을 제거합니다. 공백을 제거한 뒤에도 값이 남아 있는 문자열을 보내야 합니다. 인증 토큰에 해당하는 앱에서 수집한 ID를 사용해야 합니다. Braze Device ID나 외부 사용자 ID로 조회하려면 해당 ID와 에어브릿지 사용자를 연결한 정보가 있어야 합니다.

> `brazeDeviceId`는 브레이즈 SDK의 Device ID이며, 브레이즈의 `external_id`와 다른 값입니다.

요청 본문의 최대 크기는 65,536바이트입니다. 아래 경우에는 `422 VALIDATION_ERROR`가 반환됩니다.

* ID를 생략하거나 2개 이상 보낸 경우
* ID에 빈 문자열을 보낸 경우
* `appId`처럼 정의되지 않은 필드를 추가한 경우

### Payload 예시

사용할 ID에 맞는 요청 예시를 탭별로 확인할 수 있습니다. 예시의 ID를 예측 데이터가 준비된 실제 테스트 사용자 ID로 바꿔 주세요.

외부 사용자 ID

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

Airbridge Generated UUID

```json
{
  "userId": "1b1a2d3e-4f56-7890-abcd-ef0123456789"
}
```

Braze Device ID

```json
{
  "brazeDeviceId": "braze-device-123"
}
```

## 응답

Context API가 요청을 정상적으로 처리하면 HTTP `200`과 JSON 본문을 반환합니다. `context.lastTouchpoint`는 설치에 기여한 광고 정보입니다. `predictions`에는 구매와 이탈 모델 각각의 `probability`와 `tier`가 모두 포함됩니다.

### 응답 예시

아래 응답은 외부 사용자 ID `abc-123`으로 요청한 경우의 예시입니다. ID와 수치는 설명용 값입니다.

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

### Response body

`requestId` (`string`)

호출마다 발급되는 요청 ID입니다. 응답 헤더의 `X-Request-Id`와 같은 값이며, 오류를 확인하거나 문의할 때 사용합니다.

`appId` (`integer`)

서버가 인증 토큰으로 확인한 앱 ID입니다.

사용자 정보

`user` (`object`)

`user.id` (`string`)

요청에 사용한 ID에서 앞뒤 공백을 제거한 값입니다. 외부 사용자 ID로 요청하면 그 외부 사용자 ID를 반환합니다.

`user.type` (`string`)

요청에 사용한 ID의 종류입니다.

가능한 값

`airbridge_generated_uuid` `braze_device_id` `airbridge_external_user_id`

유입 정보

`context` (`object`)

설치 유입 정보

`context.lastTouchpoint` (`object | null`)

요청한 사용자 ID로 확인한 기기의 앱 설치에 기여한 광고 정보입니다. 조회에 성공했지만 설치 기여 결과가 없으면 null을 반환합니다.

`context.lastTouchpoint.channel` (`string | null`)

설치에 기여한 채널입니다.

`context.lastTouchpoint.campaign` (`string | null`)

설치에 기여한 캠페인입니다.

`context.lastTouchpoint.adGroup` (`string | null`)

설치에 기여한 캠페인의 광고 그룹입니다.

`context.lastTouchpoint.adCreative` (`string | null`)

설치에 기여한 광고 소재입니다.

`context.lastTouchpoint.term` (`string | null`)

광고에 설정한 키워드입니다. 앱 사용자가 실제로 입력한 검색어와 같다고 보장하지 않습니다.

예측 결과

`predictions` (`object`)

구매 예측

`predictions.d3_purchase` (`object`)

앱 설치 후 3일 이내의 구매 가능성입니다.

`predictions.d3_purchase.probability` (`number`): `0 ≤ value ≤ 1`

앱 설치 후 3일 이내에 표준 주문 완료 이벤트가 발생할 확률입니다.

`predictions.d3_purchase.tier` (`string`): `low / medium / high`

구매 모델의 학습 데이터에 대한 예측 확률 분포를 기준으로 정한 등급입니다.

이탈 예측

`predictions.d3_churn` (`object`)

앱 설치 후 3일이 지난 뒤부터 30일까지의 이탈 가능성입니다.

`predictions.d3_churn.probability` (`number`): `0 ≤ value ≤ 1`

앱 설치 후 3일이 지난 뒤부터 30일까지 활동 이벤트가 관측되지 않을 확률입니다.

`predictions.d3_churn.tier` (`string`): `low / medium / high`

이탈 모델의 학습 데이터에 대한 예측 확률 분포를 기준으로 정한 등급입니다.

### 응답 해석

구매와 이탈 모델의 예측 기간은 앱 설치 시점을 기준으로 합니다. 구매 모델이 예측하는 표준 주문 완료 이벤트는 `airbridge.ecommerce.order.completed`입니다.

예측 확률은 소수점 셋째 자리까지 반올림됩니다. 예시의 `0.723`은 72.3%를 뜻합니다. 등급은 반올림 전 확률과 각 모델의 학습 데이터에 대한 예측 확률 분포를 기준으로 정합니다. 서비스에서는 반환된 `tier`를 등급 조건으로 사용할 수 있습니다.

구매 모델과 이탈 모델은 서로 다른 사건을 예측합니다. 구매와 이탈 등급이 모두 `high`일 수 있습니다.

#### 설치 유입 정보 해석

`context.lastTouchpoint`는 설치에 기여한 채널과 캠페인 정보를 제공합니다. 설치 기여 결과가 없으면 객체 전체가 `null`입니다. 일부 정보만 없으면 해당 필드가 `null`이며, 객체에는 5개 키가 모두 포함됩니다.

`restricted`처럼 제공이 제한된 값은 전달받은 그대로 반환합니다. `unattributed`는 정보가 마스킹된 결과일 수 있습니다. 두 값 모두 `null`과 다르며, 이 값만으로 자연 유입 여부를 판단할 수 없습니다. 정보 제공이 제한되는 조건은 [확장된 프라이버시 제어(EPC)](https://help.airbridge.io/ko/guides/extended-privacy-control)에서 확인할 수 있습니다.

정상 값, 객체 전체의 `null`, 일부 필드의 `null`, `restricted`와 `unattributed`의 차이는 [설치 유입 정보의 응답 사례 비교](/docs/ko/guides/install-touchpoint#응답-사례-비교)에서 확인할 수 있습니다. 캠페인과 예측값을 조합해 화면이나 메시지를 바꾸는 예시는 [Context 활용하기](/docs/ko/guides/using-context)에서 확인할 수 있습니다.

### 오류 응답

Context API가 요청을 처리하지 못하면 오류에 해당하는 HTTP 상태 코드와 `error`를 반환합니다. 아래는 식별자 연결이나 예측 데이터를 찾지 못한 경우의 응답입니다.

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

{
  "requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a",
  "error": {
    "code": "CONTEXT_DATA_NOT_FOUND",
    "message": "Context identifier or features were not found.",
    "retryable": false
  }
}
```

프로그램에서는 `error.code`로 오류를 구분하고 `error.retryable`로 재시도 여부를 판단해야 합니다. 오류 메시지의 문구를 실행 조건으로 사용하지 않아야 합니다. 전체 오류 코드와 기본 동작은 [오류 처리](/docs/ko/reference/errors)에서 확인할 수 있습니다.