taskType ADS에 platform linkedin_ad_library를 보내고, action으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
search(기본값)는query의 키워드,advertiserName의 광고주 이름,payer의 광고비를 낸 주체, 또는 이들의 조합으로 광고를 나열합니다. 광고마다 광고주, 형식, 제목, 문구, 미디어가 있고, 응답 끝에는 받은 광고를 요약한summary가 붙습니다.ad는 광고 하나를 엽니다. 광고주, 광고비를 낸 주체, 랜딩 페이지와 함께, 라이브러리가 공개하는 경우 게재 기간, 노출 수, 도달한 국가, 타기팅을 돌려줍니다.
action advertisers는 400 VALIDATION_ERROR로 거절합니다. 경쟁사는 검색의 advertiserName으로 찾습니다.
검색은 받은 광고 30개마다 0.5크레딧입니다. ad는 0.5크레딧입니다.
요청
GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task. 라이브러리가 읽는 속도를 제한하므로 광고 120개 검색은 약 30초가 걸립니다.
경쟁사 광고 분석
요청 세 개로 경쟁사 분석을 마칩니다.- 경쟁사 이름을
advertiserName에 넣어search를 보내 광고를 나열합니다.advertiserName은 이름의 일부와 맞으므로 광고마다advertiserName을 확인합니다.query를 더해 광고를 한 주제로 좁히고,sortByoldest로 가장 오래된 광고부터 봅니다. - 광고의
libraryId로ad를 보내 광고비를 낸 주체, 랜딩 페이지를 받고, EU에 노출된 광고는 게재 기간, 노출 수, 타기팅도 받습니다. payer로search를 보내 에이전시나 회사가 어느 페이지에서 내든 비용을 낸 광고를 나열합니다.
입력
action:search(기본값),ad.query: 광고 문구의 키워드.search에는query,advertiserName,payer중 하나가 필요합니다.advertiserName: 이름. 광고주 이름의 일부와 맞춥니다(예:samsung).payer: 광고비를 낸 주체의 이름. 이름의 일부와 맞춥니다(예:Starcom).libraryId: 광고의 숫자 ID(예:1638962914).ad에 필수입니다.country: 광고가 게재된 국가의 2글자 코드, 또는 모든 국가를 뜻하는ALL(기본값).startDate,endDate:YYYY-MM-DD. 함께 보내며 최근 1년 안이어야 합니다. 두 날짜 사이에 노출된 광고를 남깁니다.sortBy:newest(기본값),oldest.limit: 광고 1-120개. 기본값은 30입니다.cursor: 이전 응답의nextCursor. 그 뒤의 광고를 이어서 받습니다.
search는 libraryId를 뺀 위의 모든 필드를 읽고, ad는 libraryId만 읽습니다. Meta 광고 라이브러리 필터(pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms, contentLanguages), 라이브러리가 검색할 수 없는 값, 액션이 읽지 않는 필드는 400 VALIDATION_ERROR로 거절하고, details가 그 필드를 알려 줍니다.
광고 더 받기
받을 광고가 더 있으면 응답에nextCursor가 붙습니다. 같은 검색에 이 값을 cursor로 보내면 다음 광고를 다시 limit만큼 받습니다. 라이브러리에 광고가 더 없으면 nextCursor는 null입니다. 커서는 그 커서를 돌려준 검색에서만 씁니다. query, advertiserName, payer, country, 날짜 범위나 sortBy가 다르면 400 VALIDATION_ERROR로 거절하고, limit은 바꿔도 됩니다.
검색 응답 예시
- 응답은
platform,action,country,query,advertiserName,payer,sortBy와 받은 날짜를 그대로 돌려줍니다.returnedCount는ads의 광고 수,hasMore는 라이브러리에 광고가 더 있으면true이며nextCursor로 이어 받고,libraryUrl은 같은 검색을 광고 라이브러리에서 엽니다. 라이브러리가 개수를 주지 않으므로totalCount는null입니다. - 광고는 카드 하나로 오며,
position,libraryId,libraryUrl,advertiserName,advertiserLogoUrl,creativeType(예:SPONSORED_STATUS_UPDATE,SPONSORED_VIDEO),format,title,body,images,videos(동영상 포스터는previewUrl),platforms(LINKEDIN)가 있습니다.format은IMAGE,VIDEO,CAROUSEL,DOCUMENT,ARTICLE,MESSAGE,JOB,SPOTLIGHT,FOLLOW_COMPANY중 하나입니다. - 메시지 광고와 thought leader 광고에는
member가 있습니다. 메시지를 보낸 사람이나 광고가 홍보하는 게시물의 작성자이며name과url을 담고,ad도 같은 형태로 돌려줍니다. 다른 광고에서는member가null입니다. - 카드에는 문구의 첫 120자가 담기고, 문구가 더 길면
bodyTruncated가true입니다.ad는 전체 문구를 돌려줍니다. advertiserId,payer,startDate,endDate,activeDays,linkUrl,landingDomain,impressions,targeting,ctaText,utm은 카드에서null입니다.ad가 라이브러리에 있는 값을 채웁니다. 라이브러리가 광고의 게재 여부를 알려 주지 않으므로isActive는null입니다.summary는 이 응답의 광고를 셉니다.ads,advertisers(광고가 가장 많은 10곳:advertiserName,ads),formats,platforms입니다. 카드에 날짜가 없으므로 날짜 필드(oldestStartDate,newestStartDate,medianActiveDays,launchesByWeek,longestRunning)는 비어 있거나null입니다.- 조건에 맞는 광고가 없는 검색은 빈
ads와 광고0개의summary로 완료됩니다.
라이브러리가 보관하는 범위
- 모든 광고의 소재, 광고주, 광고비를 낸 주체를 모든 국가에서 받을 수 있습니다.
- 게재 기간, 노출 수 범위, 국가별 노출 비중, 타기팅은 EU에 노출된 광고에서만 받을 수 있습니다.
- 라이브러리는 광고를 약 12개월간 보관하며, 날짜 필터는 최근 1년만 받습니다.
광고 하나 열기
action ad는 보낸 libraryId의 광고를 엽니다. 검색 결과나 광고 라이브러리 주소 /ad-library/detail/<libraryId>에서 얻을 수 있습니다.
ad는 전체 문구를 담은 검색 카드의 필드에advertiserId,advertiserUrl,advertiserType(company또는person),payer(광고비를 낸 주체),linkUrl,landingDomain,ctaText,startDate,endDate,activeDays,impressions,targeting,reachedCountries를 더합니다.impressions는 라이브러리가 공개하는 범위(min,max)입니다.targeting은 광고주가 포함하거나 제외한 언어와 지역(language,location)과 타기팅 매개변수(parameters:parameter,targeted,excluded)를 나열합니다. EU에 노출되지 않은 광고(예: Adobe 광고1698237666)는 날짜,impressions,targeting,reachedCountries가null입니다. 광고비를 낸 주체와 광고주는 모든 광고에 있습니다.videos는 동영상마다url(비트레이트가 가장 높은 파일),files(모든 mp4:url,type,bitrate),previewUrl을 나열합니다. 캐러셀 광고는cards(title,imageUrl)를, 문서 광고는document(제목, 페이지 수, 페이지 표지)를 더합니다.advertiser는 광고 뒤의 페이지입니다.advertiserId,advertiserName,url,type,logoUrl이 있습니다.- EU에 노출되지 않은 광고의
transparency는null입니다. EU에 노출된 광고는impressions,impressionsText(50k-100k처럼 라이브러리가 주는 텍스트),reachByCountry를 담습니다. 이 값은 EU 밖을 포함해 국가별 노출 비중(country,countryCode,share,shareText)입니다. variants는 라이브러리가 두 개 이상 보여 줄 때 광고의 다른 버전을 나열하고, 그렇지 않으면null입니다.- 소재의 미디어 URL은 수년간 열려 있습니다. 캐러셀 카드의 URL은 약 1주일 뒤, 광고주 로고는 약 2주 반 뒤 만료됩니다. 필요한 파일은 따로 저장합니다.
- 라이브러리에 광고가 없는
libraryId는PAGE_UNAVAILABLE로 실패합니다.
가격
검색은 시작할 때limit이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, limit 120 검색은 2크레딧을 보류합니다. ad는 0.5크레딧입니다. 완료된 요청만 과금합니다.