SDK에서 Event 및 User 데이터 연동 방법

이 페이지에서는 SDK를 통해 플랫폼의 유저 및 행동데이터를 연동하는 방법을 안내합니다.

사전 작업

SDK 설치

데이터 연동을 본격적으로 시작하기 전, SDK 설치 및 초기화 단계를 완료해주세요.

Marketap SDK 설치 및 초기화

프로젝트 텍소노미 확인

데이터를 연동하기 전, 현재 프로젝트에서 어떤 이벤트와 속성이 연동이 가능한지 확인해야 합니다. 아래 페이지에서 반드시 사용가능한 이벤트와 속성을 확인해주세요.

Event 및 User 텍소노미 개요

Marketap은 정의되지 않은 이벤트와 속성을 수집하지 않습니다. 반드시 이벤트를 연동하기 전 프로젝트에 정의된 텍소노미를 확인해주세요.

개요

본 페이지에서는 SDK에서 이벤트 및 사용자 정보를 어떻게 등록하고 전송해야 하는지, 그리고 정의된 텍소노미에 맞게 데이터를 연동하는 방법을 설명합니다.

연동된 데이터는 Marketap 콘솔의 오디언스, 캠페인, 대시보드 분석 등 다양한 기능의 기반이 되므로, 정확한 시점에 정확한 방식으로 연동하는 것이 매우 중요합니다.

이 가이드는 Marketap SDK를 통해 유저 식별 및 이벤트 데이터를 올바르게 연동하는 방법을 안내합니다. 유저를 올바르게 등록하지 않으면 이벤트가 누락될 수 있으므로 반드시 아래 절차를 따라야 합니다.

Marketap에서는 유저가 처음 식별되는 순간, 아래 메서드 중 하나를 호출하여 유저 ID를 SDK에 등록해야 합니다.

등록하지 않으면 이후 발생하는 이벤트가 유저에 연결되지 않아 누락될 수 있습니다. 유저와 기기간의 관계는 이 문서에서 자세하게 설명합니다.

유저 ID는 반드시 문자열 타입이어야 합니다. 숫자형을 사용하시는 경우 문자열로 변환하여 전달해주세요.

1-1. `identify()` 함수

다음과 같은 상황에서 사용합니다:

자동 로그인 등으로 이미 앱 내에서 유저가 식별된 상태인 경우
유저가 ‘정보 수정’ 페이지 등에서 이름, 생일 등 정보를 갱신한 경우

mtap.identify('USER_1234', {  // 문자열 타입이어야합니다.
  mkt_name: 'John Doe',
  mkt_email: '[email protected]',
  mkt_gender: 'male',
  mkt_cart: [{
    mkt_product_id: "PRODUCT_001",
    mkt_product_name: "Awesome Product (1)",
    mkt_product_price: 21000.00,
    mkt_quantity: 3,
  }, {
    mkt_product_id: "PRODUCT_002",
    mkt_product_name: "Awesome Product (2)",
    mkt_product_price: 15000.00,
    mkt_quantity: 1,
  }],
  mkt_coupons: [{
    mkt_coupon_id: "REGISTER_COUPON_1",
    mkt_coupon_name: "회원가입 환영 쿠폰(1)",
    mkt_issue_id: "REGISTER_COUPON_0002134",
    mkt_used_coupon: false,
    mkt_coupon_issued_at: "2025-01-01T05:39:22Z",
    mkt_coupon_expired_at: "2025-02-01T00:00:00Z"
  }],
  favorite_color: 'blue', // 커스텀 속성
  interests: ['sports', 'music'], // 커스텀 속성
});

Marketap.identify(
    userId = "USER_1234",
    properties = mapOf(
        "mkt_name" to "John Doe",
        "mkt_email" to "[email protected]",
        "mkt_gender" to "male",
        "mkt_cart" to listOf(
            mapOf(
                "mkt_product_id" to "PRODUCT_001",
                "mkt_product_name" to "Awesome Product (1)",
                "mkt_product_price" to 21000.00,
                "mkt_quantity" to 3
            ),
            mapOf(
                "mkt_product_id" to "PRODUCT_002",
                "mkt_product_name" to "Awesome Product (2)",
                "mkt_product_price" to 15000.00,
                "mkt_quantity" to 1
            )
        ),
        "mkt_coupons" to listOf(
            mapOf(
                "mkt_coupon_id" to "REGISTER_COUPON_1",
                "mkt_coupon_name" to "회원가입 환영 쿠폰(1)",
                "mkt_issue_id" to "REGISTER_COUPON_0002134",
                "mkt_used_coupon" to false,
                "mkt_coupon_issued_at" to "2025-01-01T05:39:22Z",
                "mkt_coupon_expired_at" to "2025-02-01T00:00:00Z"
            )
        ),
        "favorite_color" to "blue",  // 커스텀 속성
        "interests" to listOf("sports", "music")  // 커스텀 속성
    )
)

Android SDK에서는 미리 정의된 속성에 대한 Builder 패턴을 지원합니다.

Marketap.identify(
    userId = "USER_1234",
    properties = UserProperty.Builder()
        .setName("John Doe")
        .setEmail("[email protected]")
        .setGender(Gender.Male)
        .setPhoneNumber("01012345678")
        .setGrade("VIP")
        .setDateOfBirth(1990, 1, 1)
        .setTextMessageOptIn(true)
        .setCart(
            listOf(
                Item.Builder()
                    .setProductId("PRODUCT_001")
                    .setProductName("Awesome Product (1)")
                    .setProductPrice(21000.00)
                    .setQuantity(3)
                    .build(),
                Item.Builder()
                    .setProductId("PRODUCT_002")
                    .setProductName("Awesome Product (2)")
                    .setProductPrice(15000.00)
                    .setQuantity(1)
                    .build()
            )
        ).build()
)

Marketap.identify(
    "USER_1234",
    new HashMap<String, Object>() {{
        put("mkt_name", "John Doe");
        put("mkt_email", "[email protected]");
        put("mkt_gender", "male");

        // mkt_cart 리스트
        List<Map<String, Object>> cartList = new ArrayList<>();
        cartList.add(new HashMap<String, Object>() {{
            put("mkt_product_id", "PRODUCT_001");
            put("mkt_product_name", "Awesome Product (1)");
            put("mkt_product_price", 21000.00);
            put("mkt_quantity", 3);
        }});
        cartList.add(new HashMap<String, Object>() {{
            put("mkt_product_id", "PRODUCT_002");
            put("mkt_product_name", "Awesome Product (2)");
            put("mkt_product_price", 15000.00);
            put("mkt_quantity", 1);
        }});
        put("mkt_cart", cartList);

        // mkt_coupons 리스트
        List<Map<String, Object>> couponsList = new ArrayList<>();
        couponsList.add(new HashMap<String, Object>() {{
            put("mkt_coupon_id", "REGISTER_COUPON_1");
            put("mkt_coupon_name", "회원가입 환영 쿠폰(1)");
            put("mkt_issue_id", "REGISTER_COUPON_0002134");
            put("mkt_used_coupon", false);
            put("mkt_coupon_issued_at", "2025-01-01T05:39:22Z");
            put("mkt_coupon_expired_at", "2025-02-01T00:00:00Z");
        }});
        put("mkt_coupons", couponsList);

        // 커스텀 속성
        put("favorite_color", "blue");

        // interests 리스트
        put("interests", Arrays.asList("sports", "music"));
    }}
);

Android SDK에서는 미리 정의된 속성에 대한 Builder 패턴을 지원합니다.

Marketap.identify(
    "USER_1234",
    new UserProperty.Builder()
        .setName("John Doe")
        .setEmail("[email protected]")
        .setGender(Gender.Male)
        .setPhoneNumber("01012345678")
        .setGrade("VIP")
        .setDateOfBirth(1990, 1, 1)
        .setTextMessageOptIn(true)
        .setCart(
            Arrays.asList(
                new Item.Builder()
                    .setProductId("PRODUCT_001")
                    .setProductName("Awesome Product (1)")
                    .setProductPrice(21000.00)
                    .setQuantity(3)
                    .build(),
                new Item.Builder()
                    .setProductId("PRODUCT_002")
                    .setProductName("Awesome Product (2)")
                    .setProductPrice(15000.00)
                    .setQuantity(1)
                    .build()
            )
        )
        .build()
);

Marketap.identify(
    userId: "USER_1234",
    userProperties: [
        "mkt_name": "John Doe",
        "mkt_email": "[email protected]",
        "mkt_gender": "male",
        "mkt_cart": [
            [
                "mkt_product_id": "PRODUCT_001",
                "mkt_product_name": "Awesome Product (1)",
                "mkt_product_price": 21000.00,
                "mkt_quantity": 3
            ],
            [
                "mkt_product_id": "PRODUCT_002",
                "mkt_product_name": "Awesome Product (2)",
                "mkt_product_price": 15000.00,
                "mkt_quantity": 1
            ]
        ],
        "mkt_coupons": [
            [
                "mkt_coupon_id": "REGISTER_COUPON_1",
                "mkt_coupon_name": "회원가입 환영 쿠폰(1)",
                "mkt_issue_id": "REGISTER_COUPON_0002134",
                "mkt_used_coupon": false,
                "mkt_coupon_issued_at": "2025-01-01T05:39:22Z",
                "mkt_coupon_expired_at": "2025-02-01T00:00:00Z"
            ]
        ],
        "favorite_color": "blue", // 커스텀 속성
        "interests": ["sports", "music"] // 커스텀 속성
    ]
)

Marketap.identify(
  userId: "USER_1234",
  userProperties: {
    "mkt_name": "John Doe",
    "mkt_email": "[email protected]",
    "mkt_gender": "male",
    "mkt_cart": [
      {
        "mkt_product_id": "PRODUCT_001",
        "mkt_product_name": "Awesome Product (1)",
        "mkt_product_price": 21000.00,
        "mkt_quantity": 3,
      },
      {
        "mkt_product_id": "PRODUCT_002",
        "mkt_product_name": "Awesome Product (2)",
        "mkt_product_price": 15000.00,
        "mkt_quantity": 1,
      },
    ],
    "mkt_coupons": [
      {
        "mkt_coupon_id": "REGISTER_COUPON_1",
        "mkt_coupon_name": "회원가입 환영 쿠폰(1)",
        "mkt_issue_id": "REGISTER_COUPON_0002134",
        "mkt_used_coupon": false,
        "mkt_coupon_issued_at": "2025-01-01T05:39:22Z",
        "mkt_coupon_expired_at": "2025-02-01T00:00:00Z",
      }
    ],
    "favorite_color": "blue", // 커스텀 속성
    "interests": ["sports", "music"], // 커스텀 속성
  },
);

유저 정보 식별

다음과 같은 상황에서 사용합니다:

유저가 명시적으로 로그인하여 식별되는 경우 (예: 로그인 버튼 클릭 후)

mtap.login(user.id); // "USER_ID_1234", 문자열 타입이어야합니다.

아래와 같이 유저 정보와 이벤트 프로퍼티를 함께 전달할 수 있습니다 .

mtap.login(user.id, // "USER_ID_1234"
  {
    // 유저 속성
    mkt_name: user.name // 'John Doe',
    mkt_email: user.email // '[email protected]',
    mkt_gender: user.gender // 'Male',
  }, 
  {
    // 이벤트 속성
    is_first_login: false
  }
);

유저 프로퍼티와 이벤트 프로퍼티의 순서가 바뀌지 않도록 주의하세요.

Marketap.login(user.id); // "USER_ID_1234"

아래와 같이 유저 정보와 이벤트 프로퍼티를 함께 전달할 수 있습니다.

Marketap.login(
    userId = "USER_ID_1234",
    userProperties = mapOf(
        "mkt_name" to "John Doe",
        "mkt_email" to "[email protected]",
        "mkt_gender" to "Male"
    ),
    eventProperties = mapOf(
        "is_first_login" to false
    )
)

Marketap.login(user.id); // "USER_ID_1234"

아래와 같이 유저 정보와 이벤트 프로퍼티를 함께 전달할 수 있습니다.

Marketap.login(
    "USER_ID_1234",
    new HashMap<String, Object>() {{
        put("mkt_name", "John Doe");
        put("mkt_email", "[email protected]");
        put("mkt_gender", "Male");
    }},
    new HashMap<String, Object>() {{
        put("is_first_login", false);
    }}
);

Marketap.login(userId: user.id) // "USER_ID_1234"

아래와 같이 유저 정보와 이벤트 프로퍼티를 함께 전달할 수 있습니다 .

Marketap.login(
  userId: user.id, // "USER_ID_1234"
  userProperties: [
    // 유저 속성
    "mkt_name": user.name // 'John Doe',
    "mkt_email": user.email // '[email protected]',
    "mkt_gender": user.gender // 'Male',
  ], 
  eventProperties: [
    // 이벤트 속성
    "is_first_login": false
  ]
)

Marketap.login(userId: user.id); // "USER_ID_1234"

아래와 같이 유저 정보와 이벤트 프로퍼티를 함께 전달할 수 있습니다 .

Marketap.login(
  userId: user.id, // "USER_ID_1234"
  userProperties: {
    // 유저 속성
    "mkt_name": user.name // 'John Doe',
    "mkt_email": user.email // '[email protected]',
    "mkt_gender": user.gender // 'Male',
  }, 
  eventProperties: {
    // 이벤트 속성
    "is_first_login": false
  }
);

로그인 / 로그아웃

2. 유저 로그아웃 또는 비식별 상태 전환 시점

식별된 유저가 로그아웃하거나, 기기 초기화 등으로 더 이상 식별되지 않아야 할 경우, 아래 메서드 중 하나를 호출해야 합니다.

이 과정을 생략하면 이후 비회원 유저의 이벤트가 이전 유저에 잘못 연결될 수 있습니다. 유저와 기기간의 관계는 이 문서에서 자세하게 설명합니다.

2-1. `resetIdentity()` 함수

기기에 등록된 유저의 식별 정보를 초기화하고, 비식별 상태로 전환

이 함수는 유저를 삭제하지 않습니다. 유저에 관련된 속성과 정보는 계속 기록되어 있으며, 해당 기기와 유저의 연결만 해제합니다. 마켓탭의 기기-유저에 대한 내용은 여기 문서에서, 마켓탭의 유저 삭제에 대한 내용은 여기 문서에서 확인해주세요.

mtap.resetIdentity();

유저 정보 식별

2-2. `logout()` 함수

로그아웃 이벤트와 함께 유저 식별 정보도 초기화할 경우 사용
내부적으로 resetIdentity()를 포함하는 확장 기능입니다

기기-유저에 대한 내용은 여기 문서에서, 마켓탭의 유저 삭제에 대한 내용은 여기 문서에서 확인해주세요.

mtap.logout();

로그인 / 로그아웃

3. 이벤트 전송

플랫폼에서 발생하는 다양한 사용자 행동을 SDK를 통해 이벤트로 전송할 수 있습니다.

이벤트는 단순한 페이지 방문부터 구매, 장바구니 추가 등 주요 전환 행동까지 모두 포함할 수 있으며, 이벤트명과 함께 속성(properties)을 포함하여 Marketap 서버에 전송됩니다.

이벤트는 사전에 정의된 텍소노미(Taxonomy)를 기준으로 전송되어야 하며, 정의되지 않은 이벤트명이나 속성은 수집되지 않습니다. 관련 내용은 이 문서서 자세하게 설명합니다.

이벤트에는 반드시 식별된 사용자 정보(identify/login) 가 선행되어야 하며, 그렇지 않은 경우 이벤트에 연결된 유저의 정보가 유실될 수 있습니다. 유저와 기기간의 관계는 이 문서에서 자세하게 설명합니다.

아래는 "장바구니 담기 이벤트(mkt_add_to_cart)"의 예시입니다.

mtap.track('mkt_add_to_cart', {
  cart_total_price: 100.0,
  currency: 'USD',
  mkt_items: [
    {
      mkt_product_id: 'P12345',
      mkt_product_name: 'T-shirt',
      mkt_product_price: 25.0,
      mkt_quantity: 2,
      mkt_discount: 5.0,
      mkt_category1: '의류',
      mkt_category2: '남성복',
    },
    {
      mkt_product_id: 'P67890',
      mkt_product_name: 'Sneakers',
      mkt_product_price: 50.0,
      mkt_quantity: 1,
      mkt_category1: '신발',
      mkt_category2: '운동화',
    },
  ],
});

Marketap.track(
    event = "mkt_add_to_cart",
    properties = mapOf(
        "cart_total_price" to 100.0,
        "currency" to "USD",
        "mkt_items" to listOf(
            mapOf(
                "mkt_product_id" to "P12345",
                "mkt_product_name" to "T-shirt",
                "mkt_product_price" to 25.0,
                "mkt_quantity" to 2,
                "mkt_discount" to 5.0,
                "mkt_category1" to "의류",
                "mkt_category2" to "남성복"
            ),
            mapOf(
                "mkt_product_id" to "P67890",
                "mkt_product_name" to "Sneakers",
                "mkt_product_price" to 50.0,
                "mkt_quantity" to 1,
                "mkt_category1" to "신발",
                "mkt_category2" to "운동화"
            )
        )
    )
)

Marketap.track(
    "mkt_add_to_cart",
    new HashMap<String, Object>() {{
        put("cart_total_price", 100.0);
        put("currency", "USD");
        put("mkt_items", Arrays.asList(
            new HashMap<String, Object>() {{
                put("mkt_product_id", "P12345");
                put("mkt_product_name", "T-shirt");
                put("mkt_product_price", 25.0);
                put("mkt_quantity", 2);
                put("mkt_discount", 5.0);
                put("mkt_category1", "의류");
                put("mkt_category2", "남성복");
            }},
            new HashMap<String, Object>() {{
                put("mkt_product_id", "P67890");
                put("mkt_product_name", "Sneakers");
                put("mkt_product_price", 50.0);
                put("mkt_quantity", 1);
                put("mkt_category1", "신발");
                put("mkt_category2", "운동화");
            }}
        ));
    }}
);

Marketap.track(
    eventName: "mkt_add_to_cart",
    eventProperties: [
        "cart_total_price": 100.0,
        "currency": "USD",
        "mkt_items": [
            [
                "mkt_product_id": "P12345",
                "mkt_product_name": "T-shirt",
                "mkt_product_price": 25.0,
                "mkt_quantity": 2,
                "mkt_discount": 5.0,
                "mkt_category1": "의류",
                "mkt_category2": "남성복"
            ],
            [
                "mkt_product_id": "P67890",
                "mkt_product_name": "Sneakers",
                "mkt_product_price": 50.0,
                "mkt_quantity": 1,
                "mkt_category1": "신발",
                "mkt_category2": "운동화"
            ]
        ]
    ]
)

Marketap.track(
  "mkt_add_to_cart",
  eventProperties: {
    "cart_total_price": 100.0,
    "currency": "USD",
    "mkt_items": [
      {
        "mkt_product_id": "P12345",
        "mkt_product_name": "T-shirt",
        "mkt_product_price": 25.0,
        "mkt_quantity": 2,
        "mkt_discount": 5.0,
        "mkt_category1": "의류",
        "mkt_category2": "남성복",
      },
      {
        "mkt_product_id": "P67890",
        "mkt_product_name": "Sneakers",
        "mkt_product_price": 50.0,
        "mkt_quantity": 1,
        "mkt_category1": "신발",
        "mkt_category2": "운동화",
      },
    ],
  },
);

Marketap은 이 외에도 다양한 기본 제공 이벤트를 지원합니다. 기본 이벤트는 프로젝트 생성 시 자동으로 등록되며, 구매, 장바구니 담기, 상품 조회 등 전환 분석에 자주 활용되는 이벤트로 구성되어 있습니다.

또한, 필요에 따라 커스텀 이벤트도 자유롭게 정의할 수 있습니다. 커스텀 이벤트는 콘솔을 통해 직접 이름과 속성을 등록한 후, SDK에서 해당 이름으로 전송하면 자동으로 수집됩니다.

기본 제공 이벤트와 커스텀 이벤트의 차이점 및 정의 방법은 아래 문서를 참고해 주세요:

이벤트 정의

4. 데이터 전송 완료 후 정합

SDK를 통해 전송한 데이터가 잘 적재되었는지 마켓탭 콘솔에서 반드시 확인해야 합니다. 데이터 연동 후 체크해야하는 내용은 아래 페이지에서 확인해주세요.

데이터 연동 및 정합

이벤트 및 유저 속성이 올바르게 수집되지 않으면 오디언스 생성이나 캠페인 타게팅이 불가능합니다. 반드시 개발 후 체크리스트를 통해 연동이 올바르게 되어있는지 확인해주세요.

서버에서만 수집되는 데이터가 있다면 아래 문서를 통해 연동해주세요.

서버에서 Event 및 User 데이터 연동 방법

5. 이어서 진행하기

아래 카드를 통해 SDK 다른 기능 연동을 이어서 하실 수 있습니다. Marketap SDK가 지원하는 기능 및 연동 순서는 Marketap SDK 기능 연동 페이지를 확인해주세요.

Push Notification 연동

In-App Message 테스트

고급 기능 설정

PreviousEvent 및 User 텍소노미 개요 Next유저 정보 식별

Last updated 1 month ago

Was this helpful?

hashtag사전 작업

hashtagSDK 설치

hashtag프로젝트 텍소노미 확인

hashtag개요

hashtag1. 유저 식별 시점에 identify() 또는 login() 호출

hashtag1-1. identify() 함수

hashtag1-2. login() 함수

hashtag2. 유저 로그아웃 또는 비식별 상태 전환 시점

hashtag2-1. resetIdentity() 함수

hashtag2-2. logout() 함수

hashtag3. 이벤트 전송

hashtag4. 데이터 전송 완료 후 정합

hashtag5. 이어서 진행하기

사전 작업

SDK 설치

프로젝트 텍소노미 확인

개요

1. 유저 식별 시점에 `identify()` 또는 `login()` 호출

1-1. `identify()` 함수

1-2. `login()` 함수

2. 유저 로그아웃 또는 비식별 상태 전환 시점

2-1. `resetIdentity()` 함수

2-2. `logout()` 함수

3. 이벤트 전송

4. 데이터 전송 완료 후 정합

5. 이어서 진행하기