캠페인 웹훅

SORI를 통한 오디오 인식이 성공했을 때 사용자에게 표시됩니다. SORI 콘솔에서 등록할 수 있습니다.

개요

SORI API는 거의 실시간으로 캠페인 관련 이벤트에 대해 서버에 알리는 웹훅 기능을 제공합니다. 캠페인의 고급 설정에서 웹훅 엔드포인트를 설정하면 다음 이벤트에 대한 알림을 받을 수 있습니다:

• 캠페인 노출 캠페인이 인식되어 사용자 기기에 표시될 때 트리거됨
• 캠페인 클릭 사용자가 발견된 캠페인을 클릭하고 캠페인 액션 URL을 방문할 때 트리거됨

거의 실시간 이벤트 알림을 통해 다음과 같은 기능을 수행할 수 있습니다:

• 즉각적인 분석 실시간으로 캠페인 성과를 추적하고 분석
• 오디오 인식 기반 보상 사용자의 오디오 인식 상태에 따라 서버 측 보상 발행
• 사기 탐지 비정상적인 패턴을 즉시 모니터링하고 감지
• 실시간 대시보드 캠페인 지표의 실시간 시각화 생성

웹훅 설정

SORI는 웹훅 엔드포인트를 구성하는 두 가지 방법을 제공합니다:

전역 웹훅 URL

• 설정 섹션에서 설정
• 기본적으로 모든 캠페인에 적용
• 모든 캠페인 이벤트를 위한 중앙 엔드포인트 역할

캠페인별 웹훅 URL

• 각 캠페인의 고급 설정에서 구성 가능
• 해당 특정 캠페인에 대해 전역 웹훅 URL을 재정의
• 다른 캠페인마다 다른 처리가 필요할 때 유용

웹훅 설정 방법

1. 웹훅 이벤트를 수신할 서버에 HTTP 엔드포인트 준비
2. 다음 중 하나를 구성:

• 설정에서 전역 웹훅 URL, 또는
• 개별 캠페인 설정에서 캠페인별 웹훅 URL

3. 엔드포인트가 JSON 페이로드가 포함된 POST 요청을 처리할 수 있는지 확인

이벤트 유형

노출 및 클릭 이벤트 모두 동일한 웹훅 엔드포인트를 공유합니다. 페이로드의 event_type 필드를 사용하여 이벤트 유형을 구분할 수 있습니다.

캠페인 노출 이벤트

캠페인이 성공적으로 사용자에게 표시될 때 전송됩니다. 노출 이벤트의 경우 event_type은 impression입니다.

캠페인 클릭 이벤트

사용자가 캠페인을 클릭하고 캠페인 액션 URL로 리디렉션될 때 전송됩니다. 클릭 이벤트의 경우 event_type은 click입니다.

웹훅 이벤트 처리

엔드포인트가 웹훅 이벤트를 수신하면 이벤트 세부 정보가 포함된 JSON 페이로드가 포함됩니다. 다음은 두 이벤트 유형의 예시입니다:

노출 이벤트의 경우:

{
  "event_type": "impression",
  "material_id": "string",
  "material_name": "string",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "metadata": {
    "key": "value"
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

클릭 이벤트의 경우:

{
  "event_type": "click",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "metadata": {
    "key": "value"
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

커스텀 메타데이터

metadata 필드는 SDK에서 오는 키-값 쌍으로, 사용자나 디바이스를 식별하는 데 사용할 수 있습니다. 이 필드는 선택적입니다. 자세한 내용은 메타데이터 제공자 섹션을 참조하세요.

위치 정보에 대한 참고 사항

이는 GeoIP 추정에 기반하며 항상 정확하지 않을 수 있습니다. 정확한 정보를 사용할 수 없는 경우 Unknown 값이 제공됩니다.

응답 요구사항

웹훅 엔드포인트는 다음을 수행해야 합니다:

• 수신 확인을 위해 2xx 상태 코드로 응답
• 가능하면 차단을 방지하기 위해 이벤트를 비동기적으로 처리
• 이벤트를 멱등하게 처리(타임스탬프 사용)
• 시간 초과를 방지하기 위해 5초 이내에 응답

보안 고려사항

• 데이터 개인 정보를 보장하기 위해 가능한 웹훅 엔드포인트에 HTTPS 사용
• 수신 페이로드 구조 검증
• 웹훅 URL을 기밀로 유지

오류 처리

엔드포인트가 이벤트를 수신하지 못하는 경우 SORI API 서버는 다음을 수행합니다:

• 실패한 전송을 최대 3회까지 재시도
• 재시도 간 지수 백오프 구현
• 모든 재시도가 소진된 후 이벤트 삭제

구현 예시

Python (FastAPI)

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("event_type")

    if (event_type == "impression"):
        # 노출 이벤트 처리
        # 이벤트를 처리하는 코드를 여기에 추가, 예: 데이터베이스에 로깅
        pass
    elif (event_type == "click"):
        # 클릭 이벤트 처리
        # 이벤트를 처리하는 코드를 여기에 추가, 예: 데이터베이스에 로깅
        pass

    # 200 상태 코드로 응답
    return {"status": "success"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=3000)

NodeJS

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const eventType = payload.event_type;

  if (eventType === "impression") {
    // 노출 이벤트 처리
    // 이벤트를 처리하는 코드를 여기에 추가, 예: 데이터베이스에 로깅
  } else if (eventType === "click") {
    // 클릭 이벤트 처리
    // 이벤트를 처리하는 코드를 여기에 추가, 예: 데이터베이스에 로깅
  }

  // 200 상태 코드로 응답
  res.status(200).send({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});