# 데이터 연동 및 정합

## 사전작업 <a href="#pre-work" id="pre-work"></a>

### 이벤트, 유저 텍소노미 개요 확인 및 연동 <a href="#taxonomy" id="taxonomy"></a>

체크리스트를 가이드할 때에는, 아래 문서의 내용을 모두 이해하고 있다고 가정합니다. 문서에서는 텍소노미가 무엇인지, 어떻게 확인할 수 있는지에 대한 내용을 설명하고 있습니다.

{% content-ref url="overview" %}
[overview](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/overview)
{% endcontent-ref %}

또한, 이미 서버 및 SDK를 통해 이벤트를 전송할 준비가 되어있어야 합니다. 만약 연동을 시작하지 않았다면, 아래 문서를 통해 서버 및 SDK를 통해 이벤트를 전송하는 방법을 확인해주세요.

{% content-ref url="sdk" %}
[sdk](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk)
{% endcontent-ref %}

{% content-ref url="server" %}
[server](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/server)
{% endcontent-ref %}

### 계정 및 프로젝트 준비 <a href="#account-project" id="account-project"></a>

연동을 한 프로젝트와, 해당 프로젝트에 접근할 수 있는 계정을 준비해야 합니다.

{% hint style="danger" %}
데이터 분리가 필요한 경우 테스트용 프로젝트를 설정하는 것을 권장하며, 이때 두 프로젝트간의 설정 차이가 존재하지는 않는지 반드시 확인해야 합니다. 테스트 프로젝트에 존재하는 이벤트가, 프로덕션 프로젝트에 존재하지 않는 경우 이벤트 (혹은 속성이) 올바르게 연동되지 않을 수 있습니다.
{% endhint %}

## 연동 확인의 중요성 <a href="#validation" id="validation"></a>

{% hint style="success" %}
데이터 연동 검증은 단순한 **형식적인 절차가 아니라**, Marketap을 실서비스에 투입하기 전 반드시 거쳐야 하는 안전장치입니다.&#x20;
{% endhint %}

* 첫째, 초기 오디언스의 정확도를 확보하기 위해서입니다. 잘못 매핑된 식별자나 누락된 속성으로 오디언스를 생성하면, 캠페인 대상이 엉뚱한 고객으로 오염되어 초반 성과가 급격히 하락하고 이후 모든 분석 지표의 신뢰도가 떨어집니다.&#x20;
* 둘째, 개인정보 보호와 마케팅 규제에 대응하기 위해서입니다. 특히 수신 동의 여부나 삭제 요청이 제대로 반영되지 않으면, 불특정 다수에게 광고 메시지가 발송되어 과태료나 브랜드 신뢰도 하락 같은 법적·사업적 리스크가 발생할 수 있습니다.&#x20;
* 셋째, 보고서와 의사결정의 기반이 되는 데이터 정확성을 보장하기 위해 필요합니다. 이벤트나 유저가 일부라도 빠지면 KPI 추세 분석이 왜곡되어 향후 마케팅 전략이 잘못된 방향으로 설계될 수 있습니다.&#x20;

결국 연동 체크는 **캠페인 성과, 규제 준수, 데이터 신뢰성**이라는 세 축을 동시에 지키는 과정이며, 이를 통해 Marketap이 제공하는 세분화 마케팅과 분석의 가치를 온전히 누릴 수 있습니다.

## 단계별 연동 확인 순서 <a href="#validation-step" id="validation-step"></a>

시작하기 전, 마켓탭에 적제된 이벤트를 확인하는 방법을 아래 문서를 통해 숙지해주세요.

{% content-ref url="validation/testing" %}
[testing](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/validation/testing)
{% endcontent-ref %}

### 1. 첫 이벤트 적재, 이벤트 속성 정합 확인

#### 자동 수집 이벤트 및 속성 확인

[설치 및 초기화 가이드](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/sdk-integrating/initialize)를 따라서 SDK를 첫 설치를 했다면, Marketap SDK가 [자동으로 수집하는 이벤트](#undefined-7)(`mkt_start_session` 및 `mkt_first_visit`)가 이미 적재되어 있을 것입니다.&#x20;

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FNssu4GWMcyewAZr0sh2o%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.45.13.png?alt=media&#x26;token=c1f89aa1-ed8b-42b5-8636-735abed8420c" alt=""><figcaption></figcaption></figure>

위와 같은 이벤트를 확인하였다면  SDK를 성공적으로 설치하였습니다 :tada:

<details>

<summary>이벤트가 확인되지 않나요?</summary>

* [SDK 설치 및 초기화 가이드](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/sdk-integrating/initialize)에서 제공하는 Marketap SDK의 Initalize 함수 호출을 하였는지 확인해주세요.
* Initialize시에 사용한 Project ID가 실제 [해당 프로젝트의 ID인지](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/getting-started/marketap-overview/project-setting) 다시 확인해주세요.

{% hint style="warning" %}
Marketap은 이벤트를 수집 및 처리하는데 5\~10분정도 소요됩니다.
{% endhint %}

</details>

#### 첫 이벤트 적재 및 속성 확인

[SDK의 이벤트 연동 방법 가이드](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/sdk#id-3)를 따라서 첫 이벤트를 측정하고, 마켓탭에서 확인하여봅니다. 아래 예시는 마켓탭의 SDK를 통해 "mkt\_page\_view" 이벤트를 측정한 결과입니다.

{% hint style="success" %}
Web SDK의 경우 domain, referrer 등 페이지 관련 속성을 [자동으로 수집](#undefined-5)합니다.&#x20;
{% endhint %}

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2F3eTL1oTbSubORinzNGZ5%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.52.27.png?alt=media&#x26;token=63928371-fe82-48db-8d67-f48dc85abc48" alt=""><figcaption></figcaption></figure>

위와 같은 이벤트 및 속성을 확인하였다면, 첫 이벤트를 성공적으로 측정하였습니다 :tada:  `mkt_page_view` 이벤트 뿐만 아니라, 다양한 커스텀 이벤트 및 이벤트 속성을 사용할 수 있습니다.

<details>

<summary>이벤트 또는 이벤트 속성이 확인되지 않나요?</summary>

* 앞선 단계를 정확하게 마무리했는지 확인해주세요.
* 만약 커스텀 이벤트 (`mkt_` 로 시작하지 않는 이벤트)를 측정하였다면, 해당 이벤트가 마켓탭의 콘솔에 등록된 이벤트인지 확인해주세요.&#x20;
* 만약 속성이 확인되지 않는다면,&#x20;
  * 해당 이벤트 속성이 마켓탭의 콘솔에 등록된 이벤트 속성인지 확인해주세요.
  * 해당 이벤트 속성의 타입이 SDK에서 요청에 사용한 [값의 타입](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/data-type)과 일치하는지 확인해주세요.
  * 해당 이벤트 속성이 "아이템 하위" 속성인지 확인해주세요. 마켓탭은 아이템 하위 속성과 일반 속성을 구분하고 있습니다. 자세한 내용은 [이벤트 수집 페이지](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/event)에서 확인해주세요.

{% hint style="danger" %}
마켓탭은 등록된 이벤트가 아닌 경우 해당 이벤트를 무시합니다. ([관련 문서](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/event/predefined))
{% endhint %}

</details>

### 2. 첫 유저 적재, 유저 속성 정합 확인

#### 첫 유저 적재

[SDK의 유저 적재 방법 가이드](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/user-profile)에 따라 SDK를 통해 `login` 또는 `identify` 함수를 실행하고, 마켓탭에서 확인하여 봅니다. (아래 예시에서는 SDK를 통해 login을 호출하였습니다.)

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2F2dTjH9daxqgqGmCIecre%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.13.24.png?alt=media&#x26;token=e1303522-a610-4b20-8f6b-0030f0ca3d71" alt=""><figcaption></figcaption></figure>

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FiUD8qXbHNZ76GEcbLRey%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.21.48.png?alt=media&#x26;token=e33b7ff4-66eb-4b90-87f7-b48c147d92ac" alt=""><figcaption></figcaption></figure>

위와 같이 유저 목록에서 해당 user id를 확인하였다면, 첫 유저를 성공적으로 등록하였습니다 :tada:&#x20;

{% hint style="info" %}
마켓탭은 이름, 전화번호, 이메일과 같은 유저 민감 정보는 분석계에서 마스킹 처리하고 있습니다.
{% endhint %}

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FgTWEeJFCjjo5so5V6ske%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.28.00.png?alt=media&#x26;token=5d04a18b-7b51-47c5-8b73-97b1940a724d" alt=""><figcaption></figcaption></figure>

또한, login 함수를 사용하였기 때문에 위와 같이 이벤트 목록에서 `mkt_login` 이벤트와 로그인한 user id를 확인할 수 있습니다.

{% hint style="success" %}
만약 `identify` 함수를 통해 유저를 등록하였다면, login 이벤트는 등록되지 않습니다.
{% endhint %}

<details>

<summary>유저 정보가 확인되지 않나요?</summary>

* 앞선 단계를 정확하게 마무리했는지 확인해주세요.
* `identify` 또는 `login` 함수에 문자열 형태의 user id를 잘 입력하였는지 확인해주세요.
* 만약 속성이 확인되지 않는다면,
  * 해당 유저 속성이 마켓탭의 콘솔에 등록되었는지 확인해주세요.
  * 해당 유저 속성의 타입이 SDK에서 요청에 사용한 [값의 타입](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/data-type)과 일치하는지 확인해주세요.

{% hint style="warning" %}
Marketap은 유저 정보를 수집 및 처리하는데 5\~10분정도 소요됩니다.
{% endhint %}

{% hint style="danger" %}
마켓탭은 등록된 속성이 아닌 경우, 혹은 등록된 속성과 타입이 일치하지 않는 경우 해당 속성을 무시합니다. ([관련 문서](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/user-profile/property))
{% endhint %}

</details>

### 3. 시나리오에 따른 유저 id의 변화 확인

{% hint style="success" %}
마켓탭 SDK는 유저의 등록 상태를 내부적으로 관리하면서, 이벤트를 일으킨 주체를 추적하고 있습니다. 따라서, 이벤트에서 함께 노출되는 `user_id` 값은 이 등록 상태를 기반으로 측정합니다.  관련된 자세한 내용은 [여기 문서](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/sdk/user-profile/device)에서 확인해주세요.
{% endhint %}

#### 비회원 > 로그인 > 회원 > 로그아웃 > 비회원 시나리오 확인

SDK의 유저와 기기간의 관계를 이해하고 설정한 플랫폼에서는 비회원상태의 유저가 로그인, 로그아웃 과정을 거침에 따라 발생시킨 이벤트에 user\_id 값이 잘 반영되어 있어야 합니다. 아래는 올바르게 연동된 프로젝트에서 확인할 수 있는&#x20;

<p align="center"><strong>page view(비회원) > 로그인 > page view(회원) > 로그아웃 > page view(비회원) 시나리오</strong></p>

의 이벤트 현황입니다.

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FhK8gAPuoQNa9bwQHOK0i%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%207.42.05.png?alt=media&#x26;token=8ca12f41-fdf4-488d-8b16-cc67a7133211" alt=""><figcaption></figcaption></figure>

프로젝트마다 연동된 이벤트 상황에 따라 상이할 수 있지만, 위와 같이 로그인과 로그아웃 시점 사이에서 user id를 확인하였다면, 로그인 및 로그아웃 상황을 성공적으로 연동하였습니다 :tada:

#### 다양한 로그인 방식 테스트

연동할 몰의 특성에 따라 다양한 로그인 방식이 존재할 수 있습니다.&#x20;

* (카카오 로그인, 네이버 로그인, 구글 로그인 등) 로그인 방식 마다 로그인이 완료된 이후에도 정상적으로 로그인 로직이 동작하는지 확인해주세요.
* 자동로그인 (혹은 세션에 의한 자동 로그아웃) 과 같은 로직을 사용하는 경우, 유저의 로그인 상태가 변화할 때에도 마켓탭 SDK가 유저의 연결 상태를 적절하게 유지하는지 확인해주세요.
  * 마켓탭은 기기의 로컬 스토리지를 통해 id를 추적합니다. 따라서 자동 로그아웃이 수행된 경우에 반드시 `resetIdentity` 함수를 호출해주어야 합니다.

{% hint style="warning" %}
이외에도 유저가 로그인되어있는 상태이지만, 마켓탭의 SDK에 user id가 등록되지 않는 시나리오가 있을지 반드시 확인해야 합니다.
{% endhint %}

### 4. 유저 속성의 업데이트 확인

#### 유저 속성 업데이트

login 시점 뿐만 아니라 유저의 속성이 바뀌는 시점에도 SDK를 통해 유저 속성의 변경을 안내해야 합니다. 유저가 만약 구매를 통해 포인트를 획득하여, `identify` 함수를 통해 사용 가능 포인트를 2000으로 수정하였다면 아래와 같이 사용 가능한 포인트가 2000으로 업데이트 됩니다.

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FQMQHFWKsqaFJlQtos2Pt%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%207.59.04.png?alt=media&#x26;token=731fa520-75b0-4923-b4f6-e3f35fca7320" alt=""><figcaption></figcaption></figure>

identify 함수 혹은 API를 사용하여 유저의 속성을 업데이트 한 뒤 현황에서 변경사항을 확인하면 유저 속성의 변경에 대한 상황을 성공적으로 연동하였습니다 :tada:

#### 유저 삭제 확인

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FM5fefIq9lTMNAhANyLVY%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-16%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%208.05.12.png?alt=media&#x26;token=8aaf976e-2386-4853-834e-7fb18a2e3512" alt=""><figcaption></figcaption></figure>

[유저 삭제 API](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/server/user-deletion)를 통해 유저를 삭제하였다면, 데이터 처리 시간 이후에 유저 현황을 통해 유저가 삭제된 내역을 확인할 수 있습니다.

### 5. 액션 정합성 확인

SDK는 데이터 수집 뿐만 아니라 인앱메세지와 푸시메세지 노출 또한 담당하고 있습니다. 아래 가이드를 통해 인앱메세지 및 푸시메세지가 올바르게 동작하는지 확인해주세요.

{% hint style="warning" %}
서버를 통해 이벤트를 전송한 경우, 인앱메세지는 동작하지 않습니다.
{% endhint %}

{% content-ref url="../push-notification/overview" %}
[overview](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/push-notification/overview)
{% endcontent-ref %}

{% content-ref url="../in-app-message/in-app-campaign" %}
[in-app-campaign](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/in-app-message/in-app-campaign)
{% endcontent-ref %}

### 6. 배포 후 지표 점검

지금까지

* 시나리오에 따라 이벤트 및 유저 데이터가 잘 수집되는 것을 확인
* SDK가 캠페인 설정에 따라 메세지를 잘 노출하는 것을 확인

하였습니다. 이제 프로덕션에서 데이터를 수집할 차례입니다. 마켓탭의 SDK가 포함된 버전을 프로덕션에 배포한 뒤에 배포 사항이 잘 반영되었는지는 먼저 분석 지표를 통해 알아볼 수 있습니다.

<figure><img src="https://260547158-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTQoY0rYrzNUQxhlUfYFm%2Fuploads%2FNk4hmmj5KoMo2SRi1VWx%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202025-07-17%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.30.59.png?alt=media&#x26;token=e2d0182f-79de-46c9-b216-802ce7f74584" alt=""><figcaption></figcaption></figure>

콘솔의 인사이트 > 요약분석 탭에서는 하루 전날의 이벤트 및 유저정보를 바탕으로 요약된 분석 지표를 제공하고 있습니다. 지표에서 수집된 값 (매출액, DAU/PV 등)과 내부적으로 관리하는 데이터가 있다면, 알려진 지표와 크게 차이가 없는지 확인했다면 프로덕션에 성공적으로 배포하였습니다. :tada:

{% hint style="warning" %}
배포 프로젝트와 테스트 프로젝트가 다른 경우, 두 프로젝트의 **이벤트 / 이벤트 속성 / 유저 속성 설정이 동일**한지 확인해야 합니다.
{% endhint %}

## 이어서 진행하기 <a href="#continue" id="continue"></a>

데이터를 연동하는 과정에서 자주나오는 이슈 및 해결 방법은 아래 페이지에서 확인해주세요.

{% content-ref url="validation/trouble-shooting" %}
[trouble-shooting](https://docs.marketap.io/t3ZS4WXNMj0HK27EtIMV/developer/taxonomy/validation/trouble-shooting)
{% endcontent-ref %}