Skip to main content

Event Collection API

This is a RestAPI for collecting user event data for OPM (Omnicommerce Performance Management). By utilizing the Javascript SDK, you can easily collect user event data on most web-based or mobile web-based sites.

API Endpoint​

The default API Endpoint is as follows, and the current latest version is 2023-01.

https://opm.kr.omnicommerce.ai

caution

Please note that the Event Collection API follows different Endpoint and version policies compared to other OMNICOMMERCE APIs. Be cautious when using it.

Retrieve API key​

Authentication Key​

All OMNICOMMERCE APIs are HTTP-based REST APIs and require an authentication key to use.

  • Authentication keys are issued for each company.
  • Be cautious not to expose the API Key to the outside.

Refer to the link below to find out how to check the authentication key in OMNICOMMERCE.

How to check workspace and solution​

For accurate collection, it is recommended to collect workspace and solution information together with each event. Refer to the link below for how to check the workspace and solution.

Event Collection API​

GET /2023-01/validation/: API key authentication check​

Request Header​

NameRequiredTypeDescription
X-Api-KeyRequiredStringAPI Key

Response​

200 ok

Example Responses​

validation failed

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

POST /2023-01/events/: Send event data​

Request Header​

NameRequiredTypeDescription
X-Api-KeyRequiredStringAPI Key (Refer to: API Authentication Guide)
Content-TypeRequiredStringRequest Type. Only Application/json is supported.

Request Body​

caution

The data should be sent as an array of EventObject, and up to 100 items can be transmitted at once.

NameRequiredTypeDescription
dataRequiredList[EventObject]List of event data
EventObject​
caution

The timestamp is in Unix Timestamp format (based on milliseconds). (e.g., 1680688317472 )

NameRequiredTypeDescription
timestampRequiredDoubleEvent occurrence time. Unix Timestamp (based on milliseconds)
(e.g., 1680688317472 )
eventRequiredStringEvent type. Case-insensitive.
deviceIdRequiredStringCustomer device ID
transactionIdRequiredStringUnique ID of the event (Recommend using ULID.)
sdkVersionOptionalStringVersion of the Client SDK (e.g., 0.0.0)
sdkNameOptionalStringName of the Client SDK
osNameOptionalStringOS name
platformNameRequiredStringBrowser name (Chrome, Safari, Firefox, etc.)
prevTranIdOptionalStringPrevious transaction ID associated with the tracking event
userIdOptionalStringIdentifiable customer ID
userAgeOptionalStringUser's Age
userGenderOptionalStringUser's Gender
workspaceIdOptionalStringOmnicommerce workspace ID to be used for recommendations
solutionIdOptionalStringOmnicommerce product used
One of [CSRCH, VRCMD, SRCMD, TAGG, IMMOD]
productIdOptionalStringProduct ID
productNameOptionalStringProduct name
brandNameOptionalStringProduct brand name
productPriceOptionaldoubleDiscounted product price (original price if not discounted)
productGenderOptionalStringProduct gender
suggestQueryIdOptionalStringUnique ID of the recommended product
suggestProductIdsOptionalList[String]List of recommended product IDs
placementOptionalStringPage where event occurred
(Main, Detail, Product List etc)
labelOptionalStringKeyword for tracking or analyzing event
productLikeCountOptionaldoubleLike count of product
productReviewCountOptionaldoubleReview count of product
productReviewScoreOptionaldoubleReview score of product
strategyOptionalStringrecommendation strategy
extraOptionalObjectA key-value formatted object for adding any additional data you want to include

Solution ID​

Currently, the following Solution IDs are supported. (Refer to: Event Manager)

NameDescription
CSRCHCamera Search
VRCMDVisual Recommendations
SRCMDStyling Recommendation
TAGGAutomated Product Tagging
IMMODImage Moderation
PRCMDPersonalized 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" : "main",
            "tag": "fashion"
            "extra":{
              "productUrl": "https://test.com/123456",
              ...
            }
        },
        {
            "event": "recommend_view",
            "deviceId": "42ed9720-5168-418f-b1ab-b2a0485cd435",
            "timestamp": 1677487420237,
            "transactionId": "01GT90NCTDGP6J2MATKZNNF719",
            "osName": "Mac OS",
            "platformName": "Chrome",
            "sdkVersion": "0.0.0",
            "sdkName": "sdk bot",
            "suggestQueryId": "95826402-b04f-4829-a0ce-f60021d67794",
            "workspaceId": "test_workspace",
            "solutionId": "CSRCH",
            "prevTranId": "01GT90NCSSG3WPJT2QRTCV6M92",
            "productId": "MSC3PP2504CH"
        }
    ]
}

Response​

caution

If some events fail to collect, it would be in FailedRecordCount field

NameTypeDescription
FailedRecordCountIntegerFailed event counts to collect
RecordsList[Object]event records response list
├ Records.ErrorCodeStringError code fail to collect each events

Example Responses​

200 OK

All events collect successfully.

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

Some events failed to collect.

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

400 Bad Request

Missing required values in Event JSON

{
    "errors": "Invalid request body"
}