페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 광고반응타겟 관리

카카오모먼트

광고반응타겟 관리

이 문서는 광고반응타겟 관리 API 사용법을 안내합니다.

광고반응타겟 안내

광고반응타겟은 광고그룹 생성 및 수정 시 타게팅 정보로 활용할 수 있습니다. 광고에서 발생한 클릭, 재생, 전환 등의 반응 데이터를 조합하여 만들 수 있는 타게팅 정보입니다.

카카오모먼트 광고는 캠페인의 목표와 유형에 따라 다양한 광고 반응 데이터를 제공합니다. 사용자 선택에 따라 다양한 광고반응 데이터를 설정하여 광고반응타겟을 만들 수 있으며, 캠페인의 유형에 따라 선택할 수 있는 광고반응 데이터의 종류가 달라질 수 있습니다.

광고반응타겟 유형별 정책

광고반응타켓은 어떤 광고 유형(DISPLAY, MESSAGE)에 사용할 것인지를 고려하여 생성합니다. 광고 유형에 따라 광고반응타겟 생성에 사용할 수 있는 캠페인 유형 및 광고 반응 데이터 항목이 다릅니다. 자세한 내용은 아래 표를 참고합니다.

광고 유형: DISPLAY
생성 가능 캠페인 유형 사용 가능 광고 반응 데이터
카카오 비즈보드
카카오 비즈보드 CPT
동영상
포커스 보드
포커스 풀뷰
프로필 풀뷰		 클릭, 전환, 재생
디스플레이
다음쇼핑
상품 카탈로그
리치팝 올데이		 클릭, 전환
카카오톡 채널
개인화 메시지		 전환
광고 유형: MESSAGE
생성 가능 캠페인 유형 사용 가능 광고 반응 데이터
카카오톡 채널
개인화 메시지		 클릭, 재생, 열람

광고 반응 데이터 정의

광고 유형별 사용 가능한 광고 반응 지표의 정의가 상이합니다.

구분 클릭 재생 전환 열람
DISPLAY 광고의 클릭 영역 중에서 1곳이라도 클릭한 사용자 동영상을 3초 이상 또는 25% 이상 재생한 사용자(클릭 혹은 전환까지 한 사용자가 포함될 수 있음) 1) 카카오 픽셀 & SDK로 전환이 수집된 사용자

2) 광고로 카카오톡 채널을 추가한 사용자

- 광고 목표가 카카오톡 채널인 경우

- 애드뷰 랜딩 시 채널 추가하기 버튼 사용한 경우		 -
MESSAGE 열람한 메시지의 클릭 영역 중에서 1곳이라도 클릭한 사용자 열람한 메시지의 동영상을 3초 이상 재생한 사용자(클릭한 사용자가 포함될 수 있음) - 카카오톡 채널과의 채팅방을 열어서 메시지를 읽음 처리한 사용자

광고 반응 데이터 설정 가능 연산

광고 반응 데이터는 아래와 같은 연산으로 사용 가능합니다.

광고 반응 데이터 연산
클릭(전체) operation: ONLY
firstIndicator: CLICK
재생(전체) operation: ONLY
firstIndicator: PLAY
전환(전체) operation: ONLY
firstIndicator: CONVERSION
열람(전체) operation: ONLY
firstIndicator: OPEN
클릭-재생 operation: MINUS
firstIndicator: CLICK
secondIndicator: PLAY
재생-클릭 operation: MINUS
firstIndicator: PLAY
secondIndicator: CLICK
클릭-전환 operation: MINUS
firstIndicator: CLICK
secondIndicator: CONVERSION
열람-클릭-재생 operation: MINUS
firstIndicator: OPEN
secondIndicator: CLICK
thirdIndicator: PLAY
클릭&재생 operation: AND
firstIndicator: PLAY
secondIndicator: CLICK

광고반응타겟 목록 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/cohort/list 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고그룹 생성 및 수정 시 타게팅 정보로 활용 가능한 광고반응타겟 목록을 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 성공 시 응답 본문에 JSON 객체로 광고반응타겟의 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O

응답

본문
이름 타입 설명
- CohortTarget[] 타게팅 정보로 활용 가능한 광고반응타겟 목록
CohortTarget
이름 타입 설명
id Long 광고반응타겟 번호
audienceType String 광고반응 타겟 유형
광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용
DISPLAY, MESSAGE 중 하나
name String 광고반응타겟 이름
baseAds BaseAd[] 광고반응 데이터 목록
collectDuration Integer 수집 기간
오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함
단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
cohortStatus String 타겟 모수 상태
WAITING (준비 중),
AVAILABLE_ERROR (모출 추출 에러),
AVAILABLE (모수 추출 완료),
MODIFYING (수정 중),
DELETE (삭제 또는 삭제중),
ERROR (그 외 에러) 중 하나
popultaionScore Long 타겟 모수
타겟 모수 상태가 AVAILABLE 인 경우 정상 추출된 모수
선택한 광고에 반응한 카카오 사용자 추정 도달수로 광고반응타겟 생성 요청 후 1시간 이내 모수 추출이 완료되며 모수는 실시간 갱신됨
준비중 상태인 타겟은 모수 추출 전 단계로 타게팅에 사용 불가능
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/list" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adAccountId": 1234,
        "id": 1,
        "audienceType": "MESSAGE",
        "name": "첫번째_광고반응타겟",
        "baseAds": [
            {
                "campaign": {
                    "id": 5678,
                    "name": "첫번째_캠페인",
                    "campaignTypeGoal": {
                        "campaignType": "TALK_CHANNEL",
                        "goal": "REACH"
                    }
                },
                "adGroup": {
                    "id": 20425,
                    "name": "첫번째_광고그룹"
                },
                "operation": "ONLY",
                "firstIndicator": "OPEN"
            }
        ],
        "collectDuration": 90,
        "cohortStatus": "AVAILABLE",
        "createdDate": "2020-01-01 00:00:00",
        "lastModifiedDate": "2020-01-01 00:00:00"
    }
]

광고반응타겟 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

지정한 광고반응타겟의 상세 정보를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 정보를 조회할 광고반응타겟의 번호를 전달해야 합니다. 요청 성공 시 응답은 해당 광고반응타겟의 상세 정보 및 상태를 포함합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고반응타겟 번호 O

응답

본문
이름 타입 설명
id Long 광고반응타겟 번호
audienceType String 광고반응 타겟 유형
광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용
DISPLAY, MESSAGE 중 하나
adAccountId Long 광고계정 번호
name String 광고반응타겟 이름
baseAds BaseAd[] 광고반응 데이터 목록
collectDuration Integer 수집 기간
오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함
단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
cohortStatus String 타겟 모수 상태
WAITING (준비 중),
AVAILABLE_ERROR (모출 추출 에러),
AVAILABLE (모수 추출 완료),
MODIFYING (수정 중),
DELETE (삭제 또는 삭제중),
ERROR (그 외 에러) 중 하나
popultaionScore Long 타겟 모수
타겟 모수 상태가 AVAILABLE 인 경우 정상 추출된 모수
선택한 광고에 반응한 카카오 사용자 추정 도달수로 광고반응타겟 생성 요청 후 1시간 이내 모수 추출이 완료되며 모수는 실시간 갱신됨
준비중 상태인 타겟은 모수 추출 전 단계로 타게팅에 사용 불가능
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X GET 'https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID}' \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "name": "첫번째_광고반응타겟",
    "baseAds": [
        {
            "campaign": {
                "id": 5678,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 9012,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "collectDuration": 90,
    "cohortStatus": "AVAILABLE",
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 00:00:00"
}

광고반응타겟 생성 가능 대상 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/cohort/creatables 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟 생성하기에 필요한 정보인 광고계정 하위의 캠페인 및 광고그룹 정보의 목록을 조회합니다.

광고반응타겟 생성 가능한 캠페인 유형 X 목표의 광고그룹 정보만 조회할 수 있습니다. 생성 가능한 캠페인 유형은 광고반응타겟 유형별 정책에서 확인할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다. 검색할 캠페인의 유형 X 목표 및 이름을 선택 파라미터로 전달할 수 있습니다. 성공 시 광고그룹 및 캠페인 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
campaignType CampaignType 검색할 캠페인 유형 O
goal Goal 검색할 캠페인 목표 O
searchKeyword String 검색할 캠페인 이름 O

응답

본문
이름 타입 설명
- AdGroupAndCampaign[] 광고계정 하위의 캠페인 및 광고그룹 정보의 목록
AdGroupAndCampaign
이름 타입 설명
adGroup AdGroup 광고그룹
campaign Campaign 캠페인

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/creatables?campaignType=DISPLAY&goal=VISITING&searchKeyword=HG" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "campaignType": "DISPLAY",
            "goal": "VISITING",
            "searchKeyword":"HG"
        }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "campaign": {
            "id": 1234,
            "name": "첫번째_캠페인",
            "campaignTypeGoal": {
                "campaignType": "DISPLAY",
                "goal": "VISITING"
            }
        },
        "adGroup": [
            {
                "id": 56,
                "name": "첫번째_광고그룹"
            },
            {
                "id": 78,
                "name": "두번째_광고그룹"
            }
        ]
    }
]

광고반응타겟 생성하기

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/targetings/cohort 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟을 생성합니다. 광고반응타겟은 광고그룹 생성 및 수정 시 타게팅 정보로 활용할 수 있습니다. 광고에서 발생한 클릭, 재생, 반응 데이터를 조합하여 만들 수 있는 타게팅 정보이며 계정당 계정당 50개까지만 등록 가능합니다.

상세한 광고반응타겟 유형별 정책, 캠페인 유형별 정책, 연산 및 반응 종류 정책은 광고반응타겟 안내를 참고합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 성공 시 JSON 객체로 생성한 광고반응타겟 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
audienceType String 광고반응타겟 유형
DISPLAY, MESSAGE 중 하나		 O
name String 광고반응타겟 이름
한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음		 O
baseAds BaseAd[] 광고반응 데이터 O
BaseAd
이름 타입 설명 필수
adGroup AdGroup 광고그룹 O
campaign Campaign 캠페인 O
operation Operation 연산 종류
연산 및 반응 종류 정책 참조		 O
firstIndicator Indicator 첫 번째 반응 종류
연산 및 반응 종류 정책 참조		 O
secondIndicator Indicator 두 번째 반응 종류
연산 및 반응 종류 정책 참조		 X
thirdIndicator Indicator 세번째 반응 종류
연산 및 반응 종류 정책 참조		 X
AdGroup
이름 타입 설명
id Long 광고그룹 번호
Campaign
이름 타입 설명
id Long 캠페인 번호

응답

본문
이름 타입 설명
id Long 광고반응타겟 번호
adAccountId Long 광고계정 번호
name String 광고반응타겟 이름
collectDuration Integer 수집 기간
오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함
단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds BaseAd[] 광고반응 데이터
cohortStatus String 타겟 모수 상태
WAITING (준비 중),
AVAILABLE_ERROR (모출 추출 에러),
AVAILABLE (모수 추출 완료),
MODIFYING (수정 중),
DELETE (삭제 또는 삭제 중),
ERROR (그 외 에러) 중 하나
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/targetings/cohort" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "name": "첫번째_광고반응",
            "audienceType": "MESSAGE",
            "baseAds": [
                {
                    "campaign": {
                        "id": 56,
                        "campaignTypeGoal": {
                            "campaignType": "TALK_CHANNEL"
                        }
                    },
                    "adGroup": {
                        "id": 78
                    },
                    "firstIndicator": "OPEN",
                    "operation": "ONLY"
                }
            ]
        }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "첫번째_광고반응",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 00:00:00"
}

광고반응타겟 이름 수정하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/targetings/cohort/name 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟의 이름을 수정합니다. 이미 삭제된 광고반응타겟은 수정할 수 없으며, 수정하고자 하는 광고반응타겟 이름이 기존에 존재하는 경우에도 수정이 불가능합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 수정된 광고반응타겟 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

이 API는 사용자 계정마다 10초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고반응타겟 번호 O
name String 광고반응타겟 이름
한글, 영문, 특수문자, 공백을 허용하며
50자를 넘을 수 없음		 O

응답

본문
이름 타입 설명
adAccountId Long 광고계정 번호
id Long 광고반응타겟 번호
audienceType String 광고반응 타겟 유형
광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용
DISPLAY, MESSAGE 중 하나
name String 광고반응타겟 이름
collectDuration Integer 수집 기간
오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함
단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds BaseAd[] 광고반응 데이터
cohortStatus String 타겟 모수 상태
WAITING (준비 중),
AVAILABLE_ERROR (모출 추출 에러),
AVAILABLE (모수 추출 완료),
MODIFYING (수정 중),
DELETE (삭제 또는 삭제중),
ERROR (그 외 에러) 중 하나
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/name" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "id": 1,
            "name": "광고반응타겟_이름_수정"
        }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "광고반응타겟_이름_수정",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 12:00:00"
}

광고반응타겟 데이터 수정하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/targetings/cohort 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟의 데이터를 수정합니다.

광고반응타겟 보기 API로 기존 광고반응타겟의 정보를 조회한 후, 수정하고자 하는 필드와 수정을 원치 않는 필드를 조합하여 요청해야 합니다. 수정을 원치 않는 필드도 기존 값으로 요청해야 광고반응타겟의 정보를 유지할 수 있습니다.

타겟을 수정하면 1시간 이내에 수정된 타겟으로 업데이트됩니다. 수정 완료 전까지는 수정 전 타겟 모수로 광고그룹 타겟팅이 작동하며, 수정이 완료되면 수정된 타겟으로 광고그룹 타겟이 변경됩니다. (이 API로는 광고반응타겟 이름은 수정할 수 없습니다)

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 응답은 수정된 광고반응타겟 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 광고반응타겟 번호 O
baseAds BaseAd[] 광고반응 O
BaseAd
이름 타입 설명 필수
adGroup Long 광고그룹 O
campaign Long 캠페인 O
operation Operation 연산 종류
"ONLY","MINUS","AND" 중 하나
연산 및 반응 종류 정책 참조		 O
firstIndicator Indicator 첫 번째 반응 종류
"PLAY", "CLICK", "OPEN", CONVERSION" 중 하나
연산 및 반응 종류 정책 참조		 O
secondIndicator Indicator 두 번째 반응 종류
"PLAY", "CLICK", "CONVERSION" 중 하나
연산 및 반응 종류 정책 참조		 X

응답

본문
이름 타입 설명
id Long 광고반응타겟 번호
audienceType String 광고반응 타겟 유형
광고그룹, 오디언스 생성/수정시 올바르게 매칭하여 사용
DISPLAY, MESSAGE 중 하나
adAccountId Long 광고계정 번호
name String 광고반응타겟 이름
collectDuration Integer 수집 기간
오늘은 기준으로 수집기간 동안 쌓인 사용자 데이터를 광고 타게팅에 사용함
단, 광고집행 이력이 있어도 수집기간 내 반응한 사용자가 없는 경우 노출 대상이 없을 수 있음
baseAds BaseAd[] 광고반응 데이터
cohortStatus String 타겟 모수 상태
WAITING (준비 중),
AVAILABLE_ERROR (모출 추출 에러),
AVAILABLE (모수 추출 완료),
MODIFYING (수정 중),
DELETE (삭제 또는 삭제중),
ERROR (그 외 에러) 중 하나
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/targetings/cohort" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "id": 1234,
            "name": "광고반응타겟_데이터_수정",
            "baseAds": [
                {
                    "campaign": {
                        "id": 56,
                        "campaignTypeGoal": {
                            "campaignType": "TALK_CHANNEL"
                        }
                    },
                    "adGroup": {
                        "id": 78
                    },
                    "firstIndicator": "OPEN",
                    "operation": "ONLY"
                }
            ]
        }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId": 1234,
    "id": 1,
    "audienceType": "MESSAGE",
    "collectDuration": 90,
    "cohortStatus": "WAITING",
    "name": "광고반응타겟_이름_수정",
    "baseAds": [
        {
            "campaign": {
                "id": 56,
                "name": "첫번째_캠페인",
                "campaignTypeGoal": {
                    "campaignType": "TALK_CHANNEL",
                    "goal": "REACH"
                }
            },
            "adGroup": {
                "id": 78,
                "name": "첫번째_광고그룹"
            },
            "operation": "ONLY",
            "firstIndicator": "OPEN"
        }
    ],
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 15:00:00"
}

광고반응타겟 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟을 삭제합니다. 이미 삭제된 광고반응타겟 또는 사용 중인 광고반응타겟은 삭제할 수 없습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

이 API는 사용자 계정마다 1초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고반응타겟 번호 O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

광고반응타겟 여러 개 삭제하기

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/targetings/cohort 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

복수의 광고반응타겟을 한번에 삭제합니다. 이미 삭제된 광고반응타겟 또는 사용 중인 광고반응타겟은 삭제할 수 없습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

이 API는 사용자 계정마다 1초에 한 번씩 요청이 가능하도록 제한되어 있습니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
cohortIds String 광고반응타겟 번호
여러 개의 광고반응타겟 번호를 쉼표(,)로 구분한 하나의 문자열로 전달		 O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/targetings/cohort?cohortIds=${COHORT_ID},${COHORT_ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

광고반응타겟 사용 현황 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/targetings/cohort/usages/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목		 필요 필요

광고반응타겟 사용 현황 목록을 조회할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 광고반응타겟 번호를 전달해야 합니다. 성공 시 계정 내 해당 광고반응타겟이 타게팅에 사용된 광고그룹 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 광고반응타겟 번호 O

응답

본문
이름 타입 설명
- AdGroupAndCampaign[] 광고반응타겟 사용 현황 목록
AdGroupAndCampaign
이름 타입 설명
adGroup AdGroup 광고그룹
campaign Campaign 캠페인

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/targetings/cohort/usages/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adGroup": {
            "id": 1234,
            "name": "첫번째_광고그룹",
            "adGroupStatus": [
                "LIVE"
            ],
            "adGroupType": "DISPLAY"
        },
        "campaign": {
            "id": 5678,
            "name": "첫번째_캠페인",
            "campaignTypeGoal": {
                "campaignType": "DISPLAY",
                "goal": "VISITING"
            }
        }
    }
]

더 보기

카카오모먼트> 광고반응타겟 관리