본문으로 건너뛰기

연동 전 준비 작업

최근 업데이트 2026. 10. 07.
팁

기초 지식 섹션에서는 연동 전에 반드시 알아야 할 AE 데이터 규칙 관련 내용을 소개합니다.

연동 필수 정보 섹션에는 연동 전에 준비해야 할 시스템 파라미터가 정리되어 있습니다.

AE (Agentic Engine) 시스템은 모든 플랫폼을 아우르는 데이터 연동 솔루션을 제공합니다.

일반적으로 AE 연동은 세 단계로 진행됩니다. 먼저 비즈니스 요구 사항을 정리하여 데이터 수집 방안을 수립하며, 이 작업은 ThinkingAI 분석가가 지원합니다. 다음으로 개발 담당자가 데이터 수집 방안에 따라 데이터 연동 작업을 완료합니다. 마지막으로 데이터가 올바르게 연동되었는지 검증합니다. 연동 프로세스는 아래 그림과 같습니다:

원본 이미지 보기

데이터를 연동하기 전에 AE 시스템의 기초 지식을 이해하는 것은 매우 중요합니다. 이 문서에서는 연동에 필요한 지식을 전반적으로 소개하고, 관련 내용을 더 알아보고 싶을 때 도움을 받는 방법도 안내합니다.

이 문서는 업무 담당자, 개발자, 테스트 담당자 등 연동과 관련된 모든 분을 대상으로 합니다.

1. 개요​

AE는 모든 플랫폼을 아우르는 데이터 연동 솔루션을 제공하며, 주요 연동 방식은 다음과 같습니다:

  • 클라이언트 SDK: 디바이스 정보와 서버와 통신하지 않는 유저 행동 데이터를 수집할 수 있으며, 간단하고 사용하기 쉽습니다
  • 서버 SDK: 수집 내용이 더 정확하여 핵심 비즈니스 데이터 수집에 적합합니다
  • 데이터 가져오기 도구: 주로 과거 데이터 가져오기에 사용합니다. 서버 SDK와 LogBus를 함께 사용하는 방식도 비교적 범용적인 서버 측 데이터 수집 방안입니다

일반 앱과 Web 개발을 위해 다음을 제공합니다:

미니 게임 개발을 위해 다음을 제공합니다:

모바일 게임 개발을 위해 다음을 제공합니다:

서버 측 수집 방안으로는 서버 SDK + Logbus 방안을 권장합니다. 이 방안은 데이터 가져오기의 안정성, 실시간성, 효율성 면에서 모두 우수합니다.

이기종 과거 데이터를 가져와야 하거나 일부 데이터를 AE 시스템에 보충 입력해야 하는 경우 DataX로 가져오는 것을 고려할 수 있습니다. Logbus 방안과 달리 DataX는 상주 서비스가 아니므로 새로 생성되는 데이터를 모니터링하여 즉시 가져올 수 없고, 따라서 데이터의 실시간성을 보장할 수 없습니다. DataX의 장점은 다양한 데이터 소스의 이기종 데이터 가져오기를 지원하고 조작이 간단하다는 점입니다.

Filebeat와 Logstash로 로그를 수집하고 있으며 로그 데이터를 AE 시스템으로 가져오려는 경우 Filebeat +Logstash 방안을 사용할 수 있습니다.

데이터 수집 방안을 설계할 때는 비즈니스 상황에 따라 제품의 기술 아키텍처와 비즈니스 요구에 맞는 솔루션을 선택할 수 있습니다. 수집 방안에 대해 궁금한 점이 있으면 지원 그룹에서 분석가나 기술 지원 담당자에게 문의하십시오.

2. 기초 지식​

2.1 AE 데이터 모델​

데이터를 연동하기 전에 먼저 AE의 데이터가 무엇인지 이해해야 합니다.

데이터 수집 방안 설계는 사실 비즈니스 분석 목표에 따라 어떤 유저 행동 이벤트를 수집할지 정하는 과정입니다. 예를 들어 유저의 충전 현황을 분석하려면 유저의 결제 행동 데이터를 수집해야 할 수 있습니다. 유저 행동 데이터는 누가 (WHO), 언제 (WHEN), 어디서 (WHERE), 어떤 방식으로 (HOW) 충전 행동을 했는지 (WHAT)로 분해할 수 있으며, 아래 그림과 같습니다:

원본 이미지 보기

AE에서 유저 행동 데이터는 유저 관련 데이터와 이벤트 관련 데이터로 구성되어 각각 유저 테이블과 이벤트 테이블에 저장됩니다. 유저 데이터는 주로 유저의 상태와 자주 변하지 않는 속성을 설명합니다. 이벤트 데이터는 구체적인 행동 이벤트와 관련된 정보를 설명합니다.

데이터 수집 방안에서는 어떤 시점에 유저 데이터 전송을 트리거하고, 어떤 시점에 이벤트 전송을 트리거할지 정해야 합니다.

모든 데이터 연동 가이드에서 이벤트 데이터와 유저 데이터를 전송하는 방법을 각각 소개합니다.

2.2 유저 식별 규칙​

모든 유저 데이터와 이벤트 데이터는 해당 데이터가 어느 유저에게 속하는지 명확해야 합니다. 계정 체계가 없는 시나리오에서는 디바이스 관련 ID로 유저를 고유하게 식별할 수 있습니다. 그러나 계정 체계가 있는 시나리오에서는 한 유저가 여러 디바이스에서 데이터를 생성할 수 있고, 분석 시 여러 플랫폼에서 발생한 유저 데이터를 결합해 분석해야 하므로 디바이스 관련 고유 ID는 적합하지 않습니다.

위 두 가지 시나리오를 처리하기 위해 데이터 연동 과정에서는 두 가지 유저 ID를 결합하여 유저를 식별합니다:

  • 게스트 ID (#distinct_id): 기본적으로 클라이언트가 무작위 게스트 ID를 생성하여 유저를 식별하며, 기본 게스트 ID를 읽고 수정하는 인터페이스도 제공합니다.
  • 계정 ID (#account_id): 유저가 로그인할 때 계정 ID를 설정할 수 있습니다. 계정 ID를 통해 여러 디바이스의 데이터를 연결할 수 있습니다.

모든 데이터에는 게스트 ID 또는 계정 ID가 반드시 포함되어야 합니다. 클라이언트 SDK는 기본적으로 게스트 ID를 무작위로 생성하며, login 인터페이스를 호출하여 계정 ID를 설정한 후에는 모든 데이터를 전송할 때 게스트 ID와 계정 ID를 함께 전송합니다. 서버에서 전송하는 경우 두 ID 중 최소 하나를 전달해야 합니다.

AE 백엔드에서 유저를 식별하는 고유 ID는 AE 유저 ID(#user_id 필드)입니다. 데이터를 받으면 지정된 유저 식별 규칙에 따라 새 유저를 생성하거나 데이터를 기존 유저에 바인딩합니다.

유저 식별 규칙은 매우 중요한 내용입니다. 유저 ID를 올바르게 설정하지 않으면 데이터가 잘못된 유저에 바인딩되어 분석 결과에 영향을 줄 수 있습니다. 연동 전에 반드시 이 규칙을 자세히 숙지하고, 데이터 수집 방안에서 유저 식별 방안을 명확히 정하십시오.

2.3 데이터 형식​

어떤 방식으로 데이터를 연동하든 데이터 수신 측으로 보낼 때는 통일된 데이터 형식과 동일한 데이터 제한이 적용됩니다. 데이터 규칙 장에서 데이터 형식과 해당 데이터 제한을 자세히 설명합니다.

SDK로 데이터를 연동하는 경우 해당 인터페이스를 호출하기만 하면 SDK가 데이터를 필요한 형식으로 정리하여 전송합니다. 데이터 가져오기 도구나 Restful API로 데이터를 연동하는 경우에는 데이터 규칙의 설명에 따라 데이터 형식을 정리한 후 전송해야 합니다.

데이터 형식과 관련해서는 명명 규칙과 데이터 타입에 특히 주의해야 합니다:

  • 명명 규칙: 이벤트 이름과 속성 이름에는 영문 소문자, 숫자, 밑줄 _만 포함할 수 있으며, 영문자로 시작해야 하고 50자를 초과할 수 없습니다
  • 속성 값 데이터 타입:
AE 데이터 타입값 예시값 설명데이터 타입
숫자123,1.23데이터 범위는 -9E15 ~ 9E15Number
텍스트"ABC","상하이"문자의 기본 상한은 2KBString

시간

"2019-01-01 00:00:00","2019-01-01 00:00:00.000"

"yyyy-MM-dd HH:mm:ss.SSS" 또는 "yyyy-MM-dd HH:mm:ss". 날짜를 나타내려면 "yyyy-MM-dd 00:00:00"을 사용할 수 있습니다String
불리언true,false-Boolean
리스트["a","1","true"]

리스트의 요소는 모두 문자열 타입으로 변환됩니다

리스트에는 최대 500개의 요소를 넣을 수 있습니다

Array(String)
객체

{hero_name:"유비",hero_level:22,hero_equipment: ["자웅쌍고검","적로"],hero_if_support:False}

객체 안의 각 하위 속성(Key)은 각자의 데이터 타입을 가지며, 값 설명은 위의 해당 타입 일반 속성을 참고하십시오

객체 안에는 최대 100개의 하위 속성을 넣을 수 있습니다

Object
객체 그룹[{hero_name:"유비",hero_level:22,hero_equipment: ["자웅쌍고검","적로"],hero_if_support:False}, {hero_name:"유비",hero_level:22,hero_equipment: ["자웅쌍고검","적로"],hero_if_support:False}]

객체 그룹 안의 각 하위 속성(Key)은 각자의 데이터 타입을 가지며, 값 설명은 위의 해당 타입 일반 속성을 참고하십시오

객체 그룹 안에는 최대 500개의 객체를 넣을 수 있습니다

Array(Object)

주의: AE 백엔드에서 속성 값의 타입은 해당 속성 값을 처음 받았을 때의 타입으로 결정됩니다. 이후 데이터에서 어떤 속성 값의 타입이 이전에 결정된 타입과 맞지 않으면 해당 속성은 폐기됩니다.

AE 백엔드에서 일부 속성 이름이 #으로 시작하는 것을 볼 수 있는데, 이러한 속성은 시스템 속성입니다. 시스템 속성은 별도로 설정할 필요가 없으며 SDK가 기본적으로 수집합니다. 자세한 내용은 시스템 속성과 시스템 필드를 참고하십시오.

데이터 형식이나 데이터 타입이 올바르게 설정되지 않으면 데이터가 적재되지 않는다는 점에 특히 주의해야 합니다. 따라서 연동 단계와 연동 후에는 트래킹 방안 모듈에서 데이터 전송이 올바른지 검사하거나 관찰하고, 발생한 문제를 즉시 수정해야 할 수 있습니다.

단일 데이터의 크기는 1MB를 초과할 수 없으며, 초과하면 해당 데이터는 적재되지 않습니다.

3. 연동 필수 정보​

개발 담당자가 정식으로 데이터 연동을 진행하기 전에 다음 정보가 준비되어 있는지 확인해야 합니다:

  1. 프로젝트 APP ID: AE 백엔드에서 프로젝트를 생성할 때 프로젝트의 APP ID가 생성되며, 프로젝트 관리 페이지에서도 확인할 수 있습니다

  2. 데이터 수신 주소 확인

    • 클라우드 서비스를 사용하는 경우 수신 주소: https://global-receiver-ta.thinkingdata.cn
    • 프라이빗 배포의 경우 프라이빗 클러스터(또는 수집 노드)에 도메인을 바인딩하고 SSL 인증서를 설정해야 합니다

  3. 수신 주소 확인: 브라우저에서 https://YOUR_RECEIVER_URL/health-check에 접속하여 페이지가 ok를 반환하면 올바르게 설정된 것입니다

  4. 데이터 수집 방안에는 다음이 포함되어야 합니다:

    • 데이터 연동 방식: 클라이언트 SDK, 서버 SDK, 데이터 가져오기 도구 또는 여러 방안을 결합한 방식
    • 연동할 데이터의 내용과 트리거 시점

축하합니다! 연동 전 준비 문서를 모두 읽으셨습니다. 이제 선택한 연동 방식에 따라 해당 연동 가이드 문서를 참고하여 데이터 연동을 시작할 수 있습니다.

이 문서가 도움이 되었나요?
이 페이지의 내용