Event Collection API

OPM (Omnicommerce Performance Management) 에서 위해 사용자의 event 데이터를 수집하기 위한 RestAPI 입니다.
Javascript SDK 를 활용하면, 웹 또는 모바일 웹 기반의 대부분의 사이트에서 손쉽게 사용자의 event 데이터를 수집할 수 있습니다.

API Endpoint

기본 API Endpoint는 아래와 같으며, 현재 최신 버전은 2023-01 입니다.

https://opm.kr.omnicommerce.ai

주의

Event Collection API는 다른 OMNICOMMERCE API 와 다른 Endpoint 및 버전 정책을 따릅니다. 사용시 유의해주세요.

---

API key 조회

인증 키

OMNICOMMERCE 의 모든 API 는 HTTP 기반의 REST API이며, 사용하기 위해서는 인증키가 필요합니다.

• 인증키는 company 별로 발급됩니다.
• API Key에는 외부에 노출되지 않도록 주의가 필요합니다.

옴니커머스에서 인증키를 확인하는 방법은 아래 링크를 참고하세요.

• ↗️ API key 조회

workspace 및 solution 확인 방법

정확한 수집을 위해서 각각의 이벤트가 발생한 workspace와 solution 정보를 함께 수집하는 것을 권장합니다. Workspace와 solution 확인 방법은 아래 링크를 참고하세요.

• ↗️ Workspace 및 solution 확인 방법

---

이벤트 수집 API

GET /2023-01/validation/: api key 인증 확인

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key

Response

200 ok

Example Responses

validation 실패

{
    "errors": "User is not authorized to access this resource with an explicit deny"
}

POST /2023-01/events/: 고객 이벤트 데이터 전송

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key (참조: API 인증 가이드)
Content-Type	필수	String	요청 Type. Application/json 만 지원합니다.

Request Body

주의

data는 EventObject 의 Array 형으로 보내야 하며, 최대 100개까지 전송 가능합니다.

Name	Required	Type	Description
data	필수	List[EventObject]	event json body list.

EventObject

주의

timestamp 는 Unix Timestamp (millisecond 기준) 형식입니다. (예: 1680688317472 )

Name	Required	Type	Description
timestamp	필수	Double	Event 발생 시간. Unix Timestamp (millisecond 기준) (예: 1680688317472 )
event	필수	String	Event 종류. 대/소문자 구분 없음.
deviceId	필수	String	고객 device ID
transactionId	필수	String	event의 고유 ID (ULID 를 권장합니다.)
sdkVersion	선택	String	Client SDK의 Version (예: 0.0.0)
sdkName	선택	String	Client SDK의 이름
osName	선택	String	OS 이름
platformName	필수	String	브라우저 이름 (Chrome, Safari, Firefox 등)
prevTranId	선택	String	Tracking 용 이벤트와 연관된 이전 transaction id
userId	선택	String	식별 가능한 고객 id
userAge	선택	String	고객의 나이대
userGender	선택	String	고객의 성별
workspaceId	선택	String	추천에 사용할 omnicommerce workspace id
solutionId	선택	String	사용한 omnicommerce 제품 [CSRCH, VRCMD, SRCMD, TAGG, IMMOD, PRCMD] 중 하나
productId	선택	String	상품 id
productName	선택	String	상품 이름
brandName	선택	String	상품 브랜드명
productPrice	선택	double	상품 할인가(할인 중이 아닐 경우 원가)
productGender	선택	String	상품 성별
suggestQueryId	선택	String	Omnicommerce의 추천 쿼리 결과 id (예: Recommendation API 응답의 id 값, Camera Search API 응답의 transactionId 값)
suggestProductIds	선택	List[String]	Omnicommerce 추천 쿼리 결과 상품들의 상품 id 값의 배열
placement	선택	String	이벤트가 발생한 페이지 (메인 페이지, 상품 상세 페이지, 상품 리스트 페이지 등)
label	선택	String	이벤트 추적 혹은 분석을 위한 키워드
productLikeCount	선택	double	상품 좋아요 숫자
productReviewCount	선택	double	상품 리뷰 카운트
productReviewScore	선택	double	상품 리뷰 평점
strategy	선택	string	추천 알고리즘
extra	선택	Object	추가로 넣고자 하는 데이터를 추가할 수 있는 key-value 형태의 object

Solution ID

현재 아래와 같은 Solution ID를 지원하고 있습니다. (참조: workspace 및 solution 확인 방법)

Name	Description
CSRCH	Camera Search
VRCMD	Visual Recommendations
SRCMD	Styling Recommendations
TAGG	Automated Product Tagging
IMMOD	Image Moderation
PRCMD	Personalized Recommendations

Request Example

{
    "data": [
        {
            "event": "result_load",
            "deviceId": "42ed9720-5168-418f-b1ab-b2a0485cd435",
            "timestamp": 1677487420217,
            "transactionId": "01GT90NCSSG3WPJT2QRTCV6M92",
            "osName": "Mac OS",
            "platformName": "Chrome",
            "suggestQueryId": "95826402-b04f-4829-a0ce-f60021d67794",
            "workspaceId": "test_workspace",
            "suggestProductIds": [
                "MSC3PP2504CH",
                ...
            ],
            "solutionId": "CSRCH",
            "placement" : "메인",
            "tag": "패션"
            "extra":{
              "productUrl": "https://test.com/123456",
              ...
            }
        },
        {
            "event": "recommend_view",
            "deviceId": "42ed9720-5168-418f-b1ab-b2a0485cd435",
            "timestamp": 1677487420237,
            "transactionId": "01GT90NCTDGP6J2MATKZNNF719",
            "osName": "Chrome",
            "platformName": "Mac OS",
            "sdkVersion": "0.0.0",
            "sdkName": "sdk bot",
            "suggestQueryId": "95826402-b04f-4829-a0ce-f60021d67794",
            "workspaceId": "test_workspace",
            "solutionId": "CSRCH",
            "prevTranId": "01GT90NCSSG3WPJT2QRTCV6M92",
            "productId": "MSC3PP2504CH"
        }
    ]
}

Response

주의

이벤트 단건에 대한 수집 실패 여부는 FailedRecordCount로 알 수 있습니다.

Name	Type	Description
FailedRecordCount	Integer	event list 중 수집에 실패한 record의 갯수
Records	List[Object]	event record 응답 list
├ Records.ErrorCode	String	Record 수집 실패 사유. 수집 성공시에는 비어있는 json body가 return 됩니다.

Example Responses

200 OK

모든 이벤트 수집 성공

{
    "FailedRecordCount": 0,
    "Records": [
        {},
        {},
        ...
    ]
}

특정 이벤트 수집 실패

{
    "FailedRecordCount": 1,
    "Records": [
        {},
        {
            "ErrorCode": "ProvisionedThroughputExceededException"
        },
        ...
    ]
}

400 Bad Request

Event json 필수 값 누락

{
    "errors": "Invalid request body"
}