tagworks-sdk-v1-react-navigation

v1.1.35

Published

2 days ago

TagWorks SDK React Native Library

0High
0Medium
0Low

ny2060

react-native ios android

TagWorks SDK iOS

TagWorks SDK React Native Library

Mobile Tag 수집

Mobile Platform에서 OBZEN TagManager의 로그 수집을 하기 위한 용도의 SDK
Native 영역에서의 발생 로그 뿐만 아니라 Webview Interface 연결을 통한 웹뷰 로그도 함께 수집 가능합니다.
화면 전환 및 앱 상태 (백그라운드/포어그라운드) 전환 시 로그를 자동 수집하는 기능을 지원합니다.
앱 내에서 발생하는 크래시 로그도 자동으로 수집하는 기능을 지원합니다.
onCMS 와의 연동을 통한 개별화 팝업 기능도 지원합니다.

Requirements

react : 18.3.1
react-native : 0.76.5
최소 iOS 지원 버전 : 9.0
최소 Android Sdk 버전 : API 16
최소 Jdk 버전 : 1.8
Kotlin 버전 : 1.7.0
Build Gradle 버전 : 7.2

Installation

React-Native에서 기본적으로 지원하는 npm을 이용한 package 설치를 지원합니다.
https://www.npmjs.com 사이트에 접속 후 tagworks-sdk-v1-react 패키지를 검색하면 해당 패키지를 확인하실 수 있습니다.

1. npm을 통한 설치

해당 프로젝트의 루트 디렉토리에 설치

npm i tagworks-sdk-v1-react

iOS Dependency 설치
- iOS 폴더로 이동 후 podfile을 통해 Dependency 설치
- 신규 버전 설치 시 Podfile.lock 파일 삭제 후 재설치 권장
- 혹시라도 pod install 시 오류가 발생한다면 podfile 파일을 열어서 target 설정 구문 위에 다음 문장을 추가합니다. use_frameworks! :linkage => :static
  - React-Native는 기본 설정이 정적 라이브러리로 설치가 되는데, TagWorks iOS SDK 라이브러리는 동적 프레임워크로 설치를 해야 하기 때문에 문법에 오류가 발생할 수 있음.

cd ios
pod install --repo-update

Android Dependency 설치
Android Dependency는 Gradle을 통해 자동으로 설치되나, Dependency 연결을 위해 android 폴더 내부의 app/build.gradle 파일 내부 repositories에 maven 경로 추가

repositories {
    ...
    mavenCentral()
    maven { url "https://support.obzen.com/nexus/repository/releases/" }
}

2. 직접 설치

직접 파일로 설치하는 방식은 지원하지 않습니다.
각각의 iOS/Android OS별 Native SDK만을 설치하여 사용하고자 할 경우, 각 OS별 가이드 문서 참조 (개발팀 문의)

SDK 초기화

TagWorks SDK를 통해 로그 수집 및 기타 기능들을 이용하기 위해서는 SDK 초기화가 우선적으로 필요합니다.
필수 설정들이 이루어지지 않은 경우, 기능이 정상적으로 동작하지 않을 수 있습니다.
SDK 초기화 시점은 앱이 실행될 때 처음으로 호출되는 메서드 최상단에서 이루어져야 합니다.
TagWorks SDK 초기화 하기 위해 다음과 같은 SDK 설정값들을 지정합니다.
TagWorks SDK 초기화 방법은 아래의 OS별 초기화 방법을 참고하세요.
TagWorks SDK는 싱글톤 클래스로 유지 되기 때문에 최초 초기화 한번으로 전역에서 호출 가능합니다.

| 옵션 | 타입 | 기본값 | 설명 | | ------------------ | ------- | ----- | -------------------------------------------------------- | | siteId | string | null | 행동 정보 수집 대상 사이트 식별자 | | baseUrl | string | null | 행동 정보 데이터 수집 서버 url 주소 | | isUseIntervals | boolean | false | interval 사용 여부, false 일 경우 dispatchInterval 값이 무시되고 항상 즉시 발송된다. | | dispatchInterval | long | 3 | 행동 정보 데이터 발송 주기 (초단위, 최소 3초, 최대 10초 설정) | | sessionTimeOut | long | 5 | 행동 정보 데이터 수집 서버의 연결 대기 시간 (초단위, 최소 3초, 최대 60초 설정) | | isManualDispatch | boolean | false | 행동 정보 데이터 수동 발송 여부 | | appVersion | string | null | Application 버전 정보, 설정하지 않을 경우 내부 Application 버전 정보 전송 | | appName | string | null | Application 이름, 설정하지 않을 경우 내부 Application 이름 전송 | | isUseDynamicParameter | boolean | false | Dimension 동적 파라미터 사용 여부 (기본값 : false) | | deeplinkServerUrl | string | null | 딥링크 서비스를 사용하기 위한 Bridge 서버 URL | | |

siteId 및 baseUrl 을 설정하지 않는 경우 SDK 초기화 과정에서 오류가 발생합니다.
isUseIntervals 값을 false로 설정할 경우에는 dispatchInterval 값이 무시되고 항상 즉시 발송됩니다. true로 설정할 경우에는 dispatchInterval 값에 지정된 초를 주기로 데이터를 발송합니다.
dispatchInterval 은 큐에 저장된 행동 정보 데이터를 지정한 초만큼 주기로 발송하기 때문에, 지정한 시간 사이에 어플리케이션이 종료되는 경우 발송 할 수 없으니 적절한 시간으로 지정해야 합니다.
isManualDispatch 값을 true 로 설정한 경우에는, 명시적으로 dispatch() 함수를 호출해야만 태깅 로그가 발송됩니다.
isUseDynamicParameter 값을 true로 설정할 경우 Dimension의 key값을 문자형으로 사용하고, false로 설정할 경우 key값을 정수형으로 사용해야 합니다.
- isUseDynamicParameter 에 설정한 값에 따른 해당 메소드와는 다른 Dimension 메소드를 사용 시 데이터가 올바르게 전송되지 않을 수 있습니다.
deeplinkServerUrl 은 딥링크 서비스 이용 시 디퍼드 딥링크 사용을 하기 위해 설정한 서버 URL 입니다.

🔹 OS별 초기화 방법 (iOS, Android)

iOS

딥링크 및 자동 수집 기능을 사용하기 위해 AppDelegate의 application(_:,didFinishLaunchingWithOptions:) 메서드 최상단에서 초기화 메서드를 호출합니다.
WebView Interface 설정이 포함되어 있기 때문에 WebKit.h 헤더의 import 구문이 필요합니다.

#import <WebKit/WebKit.h>
#import "TagWorks_SDK_iOS-Swift.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    // #.TagWorks instance 설정
    TagWorks *sharedInstance = [TagWorks sharedInstance];
    [sharedInstance setInstanceConfigWithSiteId:@"00,XXXXXXXX"
                                        baseUrl:[NSURL URLWithString:@"로그 수집 Proxy 서버 URL"]
                                  isUseIntervals:YES
                    dispatchIntervalWithSeconds:1
                      sessionTimeOutWithSeconds:5
                                isManualDispatch:NO
                                      appVersion:nil
                                        appName:nil
                          isUseDynamicParameter:YES
                                  isEnabledAdId:NO
                              deeplinkServerUrl:[NSURL URLWithString:@"딥링크 Bridge 서버 URL"]];
    
    // #.딥링크로 앱이 실행될 때 실행 파라미터 전달
    NSURL *launchUrl = launchOptions[UIApplicationLaunchOptionsURLKey];
    if (launchUrl != nil) {
        [[TagWorks sharedInstance] launchWithOptionsWithUrl:launchUrl userInfo:nil];
    }
    ...
}

Android

딥링크 및 자동 수집 기능을 사용하기 위해 MainApplication의 onCreat() 메서드 최상단에서 초기화 메서드를 호출합니다.

import com.tagworkssdkv1.TagWorks;

public class MainApplication extends Application implements ReactApplication {

  @Override
  public void onCreate() {
    super.onCreate();
    ...

    TagWorks.initializeTagWorks(
        this,       // ApplicationContext 전달
        "00,XXXXXXXX",
        "로그 수집 Proxy 서버 URL",
        true,
        1,
        5,
        false,
        null,
        null,
        true,
        "딥링크 Bridge 서버 URL"
    );

    ...
  }
}

import com.tagworkssdkv1.TagWorks

class MainApplication : Application(), ReactApplication {

  override fun onCreate() {
    super.onCreate()
    ...

    TagWorks.initializeTagWorks(
        context = this,  // ApplicationContext 전달
        siteId = "00,XXXXXXXX",
        baseUrl = "로그 수집 Proxy 서버 URL",
        isUseIntervals = true,
        dispatchInterval = 1,
        sessionTimeout = 5,
        isManualDispatch = false,
        appVersion = null,
        appName = null,
        isUseDynamicParameter = true,
        deeplinkServerUrl = "딥링크 Bridge 서버 URL"
    )

    ...
  }
}

🔹 사용자 설정

TagWorks SDK 초기화 이후 TagWorksModule 클래스를 통해 행동 데이터 수집 대상이 되는 사용자를 설정하고 수집 여부를 지정합니다.
⚠️ userId 설정 시 주의 사항
- SDK 초기화 시점에 TagWorksModule.setUserId(null) 로 초기화 합니다.
- 사용자가 로그인 시점에 userId를 설정 후 로그 아웃 시점에 setUserId(null) 로 초기화 합니다.
- 앱이 백그라운드로 진입 후 앱이 다시 활성화가 된 경우, 로그인 세션 체크 후 로그아웃 상태라면 setUserId(null) 로 초기화 합니다.

| 옵션 | 타입 | 기본값 | 설명 | | ---------------- | ------- | -------- | -------------------------------------------------------- | | userId | string | null | 수집 대상 고객 식별자 (사용자 계정) | | adId | string | null | 수집 대상 광고 식별자 | | optOut | boolean | false | 행동 정보 데이터 수집 여부 (true로 지정하면 수집하지 않음) | | autoTrackingPage | boolean | true | 화면 전환 시 페이지뷰 로그 자동 수집 여부 (true - 자동 수집, false - 자동 수집 안함) | | logLevel | int | 4 | 출력할 SDK 로그 레벨 설정 (2: VERBOSE, 3: DEBUG, 4: INFO, 5: WARN, 6: ERROR) |

// 수집 대상자 고객 식별자 지정
// 고객 로그인 완료에 따라 수집 대상자 고객 식별자를 지정합니다.
TagWorksModule.setUserId(loginId);

// SDK 디버그 용도 로그 출력
TagWorksModule.setLogLevel(3);

// 고객이 설정한 개인정보 수집 여부에 따라 수집 여부 지정
// 로그인을 완료한 사용자의 개인정보 수집여부를 판단하여 행동데이터의 수집 여부를 지정합니다.
// 태깅 로그 전송 제어 용도로도 사용 가능합니다.
TagWorksModule.setOptOut(false);

// 화면 이동시 로그 자동 수집 여부 설정
TagWorksModule.setAutoTrackingPage(true);

// 수집 대상자 광고 식별자 지정 (기본적으로 가져오도록 설정됨.)
TagWorksModule.setAdId("광고식별자 UUID");

SDK 클래스 선언

TagWorks SDK 사용을 위해 다음과 같이 import 및 클래스를 선언합니다.
SDK 모듈들과 딥링크, omCMS 연동 팝업/배너를 사용하기 위한 클래스들을 import 합니다. (OnCmsBannerView 포함)
NativeModules를 이용하여 SDK 모듈들의 클래스들을 선언해줍니다.

import { NativeModules, Linking, NativeEventEmitter } from 'react-native';
import { OnCmsBannerView, TagWorksDeeplink } from 'tagworks-sdk-v1-react';
...
const { TagWorksModule, DataBundleModule, StandardEventModule, TagWorksPopupModule, TagWorksDeeplinkModule } = NativeModules;

데이터 구성

서버로 전송할 태그 정의 데이터를 구성합니다.

🔹 Dimension

디멘젼은 Tagworks SDK를 통해 로그 발송 시 사용자 행동 정보를 수집하는 데이터 정보입니다.
공용 디멘젼은 한번 설정하면 일반 디멘젼과 함께 로그 발송 시 전달이 되며, TagWorks SDK 인스턴스에 할당이 되어 삭제를 하지 않는 한 계속 정보를 가지고 있습니다.
일반 디멘젼은 로그 발송 시 파라미터로 전달이 되는 DataBundle 객체에 담기는 행동 정보로, 일반적으로 지역 변수로 처리 시 로그 전송 후 정보가 초기화되어 사라집니다.
로그 전송 시 항상 전달이 되어야 하는 정보들은 보통 공용 디멘젼에 할당을 하여 사용하며, 일회성으로 사용하는 정보들은 일반 디멘젼 사용 하시는 것을 권고드립니다.
해당 디멘젼 관련 내용은 iOS/Android 동일합니다.
문자형과 숫자형 두 개의 타입 중 원하는 타입을 선택하여 사용할 수 있습니다. (숫자형은 수치데이터 정보를 이용한 통계 목적으로 사용 가능)
key & value 형태로 값을 지정할 수 있으며, key 부분에는 숫자형 index를 사용합니다.
- 입력하는 index 값은 TagManager 제품에서 정의된 값으로 프로젝트 진행시 전달받을 수 있습니다.
index는 문자형과 숫자형에서 중복이 될 수는 있지만, 각각 타입에서 index가 중복으로 사용되면 기존 index에 값이 할당되니 유의하시기 바랍니다.

🔹 공용 Dimension

공용 Dimension은 수집 로그 전송 시 공통적으로 전송해야 할 데이터를 설정하는 용도로 사용합니다.
공용 Dimension에서 사용된 index에 다른 Dimension을 덮어쓰지 않는 이상 한 번 설정된 공용 Dimension은 계속 유지됩니다.
setCommonDimension() / setDynamicCommonDimension() 함수를 사용하여 공용 Dimension 항목을 계속 추가할 수 있습니다.
getCommonDimension() / getDynamicCommonDimension() 함수를 사용하여 공용 Dimension 항목들을 가져올 수 있습니다.

🔸 Dimension 추가

// 
// # Set 
// index를 사용하여 설정 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용)

// Dimension - String Type
TagWorksModule.setCommonDimensionWithString(1, "계좌조회");

// Dimension - Numeric Type (Double형)
TagWorksModule.setCommonDimensionWithDouble(2, 30000.0);

// 
// # Set 
// 동적 파라미터 key 값을 사용하여 설정 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// Dimension - String Type
TagWorksModule.setDynamicCommonDimensionWithString("사용자행동01", '설정정보01');

// Dimension - Numeric Type (Double형)
TagWorksModule.setDynamicCommonDimensionWithDouble("사용자행동02", 10000.0);

🔸 Dimension 가져오기

//  
// # Get 
// 타입과 index를 사용하여 가져오기 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용)

// 타입별로 index 키를 가지고 해당 값을 리턴
// - return : String or Double
TagWorksModule.getCommonDimensionWithString(1, (value) => {
  console.log(value);  
});
TagWorksModule.getCommonDimensionWithDouble(2, (value) => {
  console.log(value);  
});

// GeneralType(String)과 FactType(Double) 별로 리턴
// - return : JSONString
TagWorksModule.getCommonDimensions((jsonString) => {
    console.log('Received CommonDimensions String:', jsonString);
});

// 공용 Dimension 정보를 가지고 있는 Array의 Index 순으로 리턴 
// - return : JSONString
TagWorksModule.getCommonDimensionsOfArrayIndex((jsonString) => {
    // JSON 문자열을 객체로 파싱
    const parsedData = JSON.parse(jsonString);
    console.log('Received Dimensions ArrayIndex String:', parsedData);
});

//  
// # Get 
// 동적 파라미터 key 값을 사용하여 가져오기 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// key 값을 가지고 해당 값을 리턴
// - return : String or Double
TagWorksModule.getDynamicCommonDimension("사용자행동01", (value) => {
    console.log(value);
});

// key 값 별로 리턴
// - return : JSONString
TagWorksModule.getDynamicCommonDimensions((jsonString) => {
    console.log('Received CommonDimensions String:', jsonString);
});

// 공용 Dimension 정보를 가지고 있는 Array의 Index 순으로 리턴 
// - return : JSONString
TagWorksModule.getDynamicCommonDimensionsOfArrayIndex((jsonString) => {
    // JSON 문자열을 객체로 파싱
    const parsedData = JSON.parse(jsonString);
    console.log('Received Dimensions ArrayIndex String:', parsedData);
});

🔸 Dimension 삭제

//  
// # Delete 
// 타입과 index를 사용하여 삭제하기 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용)

// 타입별 index 키를 가지고 삭제
TagWorksModule.removeCommonDimensionInGeneralType(1);
TagWorksModule.removeCommonDimensionInFactType(2);

// 공용 Dimension 정보를 가지고 있는 Array의 Index를 이용해 삭제
TagWorksModule.removeCommonDimensionWithArrayIndex(0);

// 모든 공용 Dimension을 삭제
TagWorksModule.removeAllCommonDimension();

//  
// # Delete 
// 동적 파라미터 key 값을 사용하여 삭제하기 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// 키 값을 가지고 삭제
TagWorksModule.removeDynamicCommonDimension("사용자행동02")

// 공용 Dimension 정보를 가지고 있는 Array의 Index를 이용해 삭제
TagWorksModule.removeDynamicCommonDimensionWithArrayIndex(0);

// 모든 공용 Dimension을 삭제
TagWorksModule.removeAllDynamicCommonDimension();

🔹 DataBundleModule

수집 로그 전송을 하기 위해 필요한 정보들을 담는 클래스로 기본 파라미터 및 Dimension 정보를 쉽게 관리할 수 있습니다.
DataBundleModule 클래스는 key와 value의 집합으로 구성된 컨테이너입니다.
태그명 Key에 대응하는 값으로는 DataBundle 클래스가 제공하는 기본 태그 값을 사용하거나, 사용자 정의 String 값을 직접 입력할 수 있습니다.
기본적으로 EVENT_TAG_NAME 값을 설정하지 않는 경우, 로그 전송이 이루어지지 않습니다.
putDimensions() 또는 putDynamicDimension() 메소드를 이용하여 Dimension 객체를 DataBundle 내부에 추가하여 개별 디멘젼으로 사용할 수 있습니다.

🔸 DataBundleModule 클래스의 key 값으로 사용 가능한 파라미터

| 파라미터 (키) | 타입 | 설명 | | -------------------------------| ------ | ---------------------------------------- | | EVENT_TAG_NAME | string | 태그명 | | EVENT_TAG_PARAM_TITLE | string | 태그 화면 타이틀 | | EVENT_TAG_PARAM_PAGE_PATH | string | 태그 화면 경로 | | EVENT_TAG_PARAM_KEYWORD | string | 태그 검색어 | | EVENT_TAG_PARAM_CUSTOM_PATH | string | 태그 사용자 정의 경로 - 추가 분석을 위한 경로 | |

🔸 EVENT_TAG_NAME 에 대응하는 값으로 사용할 수 있는 Standard 태그

| EVENT_TAG_NAME | 설명 | | -------------- | -------------------- | | PAGE_VIEW | 페이지뷰 태그 | | CLICK | 클릭 태그 | | SCROLL | 화면 스크롤 태그 | | DOWNLOAD | 파일 다운로드 태그 | | OUT_LINK | 링크 이동 태그 | | SEARCH | 검색 태그 | | ERROR | 오류 발생 태그 | | REFERRER | 유입 경로 태그 | |

🔸 DataBundleModule 초기화

// DataBundleModule을 사용하기 위해 필요한 초기화
DataBundleModule.initialize();

// JSON String을 이용해 초기화
// 기존의 DdataBundleModule의 설정 값을 JSON String으로 저장 후 해당 String을 이용해 빠르게 초기화 할때 사용
DataBundleModule.initDataBundle(bundleString);

🔸 DataBundleModule 파라미터 설정

// 태그명 - Standard 태그 or 사용자 정의 태그명
DataBundleModule.putString(DataBundleModule.EVENT_TAG_NAME, StandardEventModule.PAGE_VIEW);
// 화면(뷰) 타이틀
DataBundleModule.putString(DataBundleModule.EVENT_TAG_PARAM_TITLE, "화면타이틀");
// 화면 경로
DataBundleModule.putString(DataBundleModule.EVENT_TAG_PARAM_PAGE_PATH, "/화면경로");
// 검색어
DataBundleModule.putString(DataBundleModule.EVENT_TAG_PARAM_KEYWORD, "검색어");
// 사용자 정의 url
DataBundleModule.putString(DataBundleModule.EVENT_TAG_PARAM_CUSTOM_PATH, "/사용자정의 경로");

🔸 DataBundleModule 개별 디멘젼 설정

// 
// # Set 
// 타입과 index를 사용하여 Dimension 설정 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용)

// Dimension - String Type
DataBundleModule.putDimensionWithString(11, "나의계좌");

// Dimension - Numeric Type (Double형)
DataBundleModule.putDimensionWithDouble(12, 10000);

// 
// # Set 
// 동적 파라미터 key 값을 사용하여 설정 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// Dimension - String Type
DataBundleModule.putDynamicDimensionWithString("사용자행동01", '설정정보01');

// Dimension - Numeric Type (Double형)
DataBundleModule.putDynamicDimensionWithDouble("사용자행동02", 10000.0);

//  
// # Get 
// 타입과 index를 사용하여 Dimension 가져오기 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용) 

// 타입별로 index 키를 가지고 해당 값을 리턴
// - return : String or Double
DataBundleModule.getDimensionWithString(1, (value) => {
    console.log(value);  
});
DataBundleModule.getDimensionWithDouble(2, (value) => {
    console.log(value);  
});

// GeneralType(String)과 FactType(Double) 별로 리턴
// - return : JSONString
DataBundleModule.getDimensions((jsonString) => {
    console.log('Received DataBundle Dimensions String:', jsonString);
});

// 개별 Dimension 정보를 가지고 있는 Array의 Index 순으로 리턴 
// - return : JSONString
DataBundleModule.getDimensionsOfArrayIndex((jsonString) => {
    // JSON 문자열을 객체로 파싱
    const parsedData = JSON.parse(jsonString);
    console.log('Received DataBundle Dimensions ArrayIndex String:', parsedData);
});

//  
// # Get 
// 동적 파라미터 key 값을 사용하여 가져오기 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// key 값을 가지고 해당 값을 리턴
// - return : String or Double
DataBundleModule.getDynamicDimension("사용자행동01", (value) => {
    console.log(value);
});

// key 값 별로 리턴
// - return : JSONString
DataBundleModule.getDynamicDimensions((jsonString) => {
    console.log('Received DataBundle Dimensions String:', jsonString);
});

// 개별 Dimension 정보를 가지고 있는 Array의 Index 순으로 리턴 
// - return : JSONString
DataBundleModule.getDynamicDimensionsOfArrayIndex((jsonString) => {
    // JSON 문자열을 객체로 파싱
    const parsedData = JSON.parse(jsonString);
    console.log('Received DataBundle Dimensions ArrayIndex String:', parsedData);
});

//  
// Delete 
// 타입과 index를 사용하여 삭제하기 (SDK 초기화 설정 시 isUseDynamicParameter를 false로 설정한 경우 사용)

// 타입별 index 키를 가지고 삭제
DataBundleModule.removeDimensionInGeneralType(11);
DataBundleModule.removeDimensionInFactType(22);

// 개별 Dimension 정보를 가지고 있는 Array의 Index를 이용해 삭제
DataBundleModule.removeDimensionWithArrayIndex(0);

// 모든 개별 Dimension을 삭제
DataBundleModule.removeAllDimension();

//  
// Delete 
// 동적 파라미터 key 값을 사용하여 삭제하기 (SDK 초기화 설정 시 isUseDynamicParameter를 true로 설정한 경우 사용)

// key 값을 가지고 삭제
DataBundleModule.removeDynamicDimension("사용자행동01");

// 개별 Dimension 정보를 가지고 있는 Array의 Index를 이용해 삭제
DataBundleModule.removeDynamicDimensionWithArrayIndex(0);

// 모든 개별 Dimension을 삭제
DataBundleModule.removeAllDynamicDimension();

로그 전송

logEvent() 함수를 호출하여 로그를 전송합니다.
로그 타입에는 페이지뷰 태그, 사용자 태그 두 가지 타입이 존재합니다.
로그 타입이 TagWorks.EVENT_TYPE_PAGE 인 경우
- EVENT_TAG_NAME 값이 StandardEvent.PAGE_VIEW 인 경우, EVENT_TAG_PARAM_PAGE_PATH 값은 필수 파라미터입니다.
로그 타입이 TagWorks.EVENT_TYPE_USER_EVENT 인 경우
- EVENT_TAG_NAME 값이 StandardEvent.SEARCH 인 경우, EVENT_TAG_PARAM_KEYWORD 값은 필수 파라미터입니다.
앞서 설정한 DataBundleModule 로부터 설정 상태를 JSON String으로 받아와 파라미터로 전송

DataBundleModule.getDataBundle((bundleString) => {
    console.log('Received Dictionary String:', bundleString);

    TagWorksModule.logEvent(TagWorksModule.EVENT_TYPE_PAGE, bundleString, (result) => {
        console.log(result)
    });
});

Web View 연동

Web / App 연동을 위한 interface 를 제공합니다.
앱에서 Tag Manager Code Snippet 이 포함된 웹뷰를 실행하면, 웹뷰에서 발생된 태깅 로그는 SDK를 통하여 앱으로 전송됩니다.
WebView의 onMessage 내부에 TagWorksModule의 webInterfaceDidReceive() 함수 호출이 필요합니다.
로그인 시 사용자 맵핑을 위해 로그인 시점에 userId 설정하는 부분과 App에서 설정한 Dimension 값을 WebView에서 사용하기 위해 쿠키를 설정하는 부분에 있어 부분적인 대응 개발이 필요할 수 있습니다.

  <WebView
      ...
      injectedJavaScript={`
      window.__TAGWORKS_SDK_READY = true;
      true; // <- 이건 iOS에서 필요 (스크립트가 유효한 값을 반환해야 주입 성공으로 인식됨)
      `}
      javaScriptEnabled={true}    // JavaScript 활성화
      onMessage={(event) => {
          const message = event.nativeEvent.data;
          console.log("Received message: ", message);
          TagWorksModule.webInterfaceDidReceive(message);
      }}
  />

유입 경로 설정 (단순 URL 저장)

Referrer 정보가 포함되어 있는 스키마 URL로 부터 앱이 실행이 된 경우, 해당 스키마 URL 정보를 서버로 수집이 가능합니다.
앱에서 해당 URL 정보를 받아오는 메서드 내부에 다음과 같은 TagWorks SDK 인터페이스를 호출합니다.

TagWorksModule.sendReferrerEventWithOpenUrlString("<referrer url>");

Crash Error Report (앱 크래시 발생 시 크래시 로그 저장 및 발송)

SDK에서는 기본적으로 Native 앱 크래시 로그를 수집합니다.(React-Native는 RSoD 상태로 수집 불가)
수동으로 앱 크래시 로그를 수집 서버로 전송하고 싶은 경우에 해당 인터페이스를 사용합니다.
앱에서 크래시(비정상종료) 발생 시 앱 내 catch() 구문이 실행 된 경우, 해당 메소드를 통해 크래시 로그를 로컬에 저장합니다.
앱이 재실행되면서 SDK 초기화 메소드가 호출되는 시점에 로컬에 저장되어 있는 크래시 로그를 SDK에서 자동으로 수집 서버로 전송합니다.
현재 해당 기능은 DataBundle의 커스텀 디멘젼을 이용해 발송하기 때문에 동적 파라미터를 설정해서 사용을 하는 경우, TagManager -> 수집 항목 -> SDK 에서 항목 추가를 통해 다음 세가지 컬럼을 추가하여야만 해당 로그를 확인할 수 있습니다.
- obz_err_type (에러 구분 코드)
- obz_err_data (에러 메세지)
- obz_err_time (에러 발생 시간 (KST))

메소드 파라미터 설명

| 파라미터 | 타입 | 설명 | | --------------- | ------ | --------------------------------------------------------- | | errorType | String | 에러 구분 코드 (exception / signal / fatalerror 등등) | | errorMessage | String | stack track 스트링 또는 크래시 발생 시 해당 조건값/로그 등등 | | |

  const stack = e.stack || e.toString();
  TagWorksModule.saveErrorReport('에러 타입', stack);   // 에러 메세지는 임의로 작성 가능

InAppMessage

onCMS Popup

onCMS 연동을 통해 앱 내 팝업을 노출할 수 있습니다.
onCMS 추천 영역 설정을 통해 가운데 팝업, 하단 슬라이드 팝업, 전체 페이지 팝업 형태로 노출 가능합니다.

onCMS Popup을 노출하기 위해 필요한 파라미터

| 파라미터 | 타입 | 설명 | | ------------ | ------- | ---------------------------------------------------------------- | | onCmsUrl | String | 고객사에 설치된 onCMS 서버 URL (예: "https://lab.obzen.com/oncms") | | cust_id | String | 고객 번호 | | rcmd_area_cd | String | 추천 영역 코드 | | |

TagWorksPopupModule.onCMSPopup(
    "https://onCMSUrl",
    "고객번호",
    "추천영역코드"
);

onCMS Banner

onCMS 연동을 통해 앱 내 설정한 네이티브 영역에 배너를 노출할 수 있습니다.
onCMS 추천 영역 설정을 통해 단일 배너, 롤링 배너, 리스트 배너 형태로 노출 가능합니다.
onCmsBannerView 네이티브 커스텀 뷰의 Property 설정을 이용합니다. (useState 이용)
호출 시 마다 뷰의 렌더링을 갱신하기 위해 해당 View 의 key 설정을 이용합니다.
defaultImage 리소스는 React-Native 프로젝트가 아닌 각각의 네이티브 프로젝트 내 리소스로 추가하여야 합니다.
- iOS는 Images 내부가 아닌 프로젝트 루트에 파일로 추가, Android는 res/drawable 폴더 내 추가

onCMS Banner를 노출하기 위해 필요한 파라미터

| 파라미터 | 타입 | 설명 | | ------------ | -------------------------------- | ----------------------------------------------- | | onCmsUrl | String | 고객사에 설치된 onCMS 서버 URL (예: "https://lab.obzen.com/oncms") | | cust_id | String | 고객 번호 | | rcmd_area_cd | String | 추천 영역 코드 | | defaultImage | String | 로딩되기 전에 보여줄 디폴트 이미지 이름 (확장자 제외) |

변수 선언

  const [onCmsUrl, setOnCmsUrl] = useState('');
  const [custId, setCustId] = useState('');
  const [areaCode, setAreaCode] = useState('');
  const [imageName, setImageName] = useState('default_image');
  const [bannerKey, setBannerKey] = useState(0);

Banner View 영역 할당

해당 배너 노출 View 영역 노출
style은 onCMS 에서 설정된 추천영역 배너 크기에 맞게 설정

  <OnCmsBannerView
    key={`banner-${bannerKey}`}
    style={{ width: '100%', height: 200 }}
    onCmsUrl={onCmsUrl}
    cust_id={custId}
    rcmd_area_cd={areaCode}
    defaultImage={imageName}
  />

변수 값 할당

필요한 파라미터 값들이 준비되면 내부적으로 함수 호출을 통해 값들을 설정

  const callBannerView = () => {
    setOnCmsUrl('https://onCMSUrl');
    setCustId('고객번호');
    setAreaCode('추천영역배너');
    setImageName('default_image');
    setBannerKey((prev) => prev + 1);
  };

딥링크 서비스

TagWorks Deeplink Service는 앱 설치 및 실행 시 딥링크를 처리하고, 지연된 딥링크(Deferred Deeplink)를 지원하는 고급 딥링크 처리 시스템입니다.
딥링크 서비스를 이용하여 유입 분석 및 성과 측정이 가능합니다.
유니버셜 링크, 앱 링크는 지원하지 않습니다.

✅ TagWorks Deeplink Service는 다음과 같은 기능을 제공합니다.

즉시 딥링크 처리 : 앱이 실행될 때 딥링크 URL을 즉시 처리
지연된 딥링크 처리 : 앱 설치 후 첫 실행 시 딥링크 정보를 서버에서 조회하여 처리
자동 이벤트 로깅 : 딥링크 관련 이벤트를 자동으로 수집 서버에 전송
설치 시간 기반 필터링 : 앱 설치 후 3일 이내에만 지연된 딥링크 처리

딥링크(Deferred 딥링크)

TagManager로부터 생성한 마케팅 URL로부터 앱으로의 유입 경로 및 설치 정보를 분석할 수 있습니다.
딥링크를 처리하기 위해서는 SDK 초기화 메서드 호출이 필히 선행되어야 하며, SDK 초기화 시 deeplinkServerUrl 파라미터에 올바른 딥링크 Bridge 서버 URL이 필요합니다.
앱이 실행되는 진입점 메서드 최상단에서 SDK 초기화 메서드를 호출해야 합니다.
- iOS: AppDelegate의 application(_:,didFinishLaunchingWithOptions:)
- Android: Application의 onCreate()

딥링크 설정

딥링크 설정은 각각의 Native에서 다음과 같은 설정이 필요합니다.

🔹 iOS

앱이 종료 상태에서 딥링크를 통해 앱이 실행이 될 때, 실행되는 진입점인 AppDelegate의 application(_:,didFinishLaunchingWithOptions:) 메서드 최상단에서 SDK 초기화 메서드를 호출 후 바로 launchWithOptions(url:userInfo:) 메서드를 호출해야 합니다.
앱이 실행 중인 상태에서 딥링크를 처리하기 위해서는 application(:openurl:options:) 또는 scene(:openURLContexts:) 메서드 구현이 필수로 필요합니다. 해당 메서드가 구현이 되어 있어야 SDK에서 자동으로 딥링크를 처리할 수 있습니다.

1. 앱 내 스키마 등록 (App 프로젝트 설정)

앱 타겟의 Info.plist 항목에 URL types 항목을 추가합니다.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.example.myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myappscheme</string>
    </array>
  </dict>
</array>

| 파라미터 | 설명 | 필수 여부 | |-----------------------|---------------------------------------------------|-----------| | CFBundleURLName | 스키마를 구분할 수 있는 식별자. 보통 BundleId에 식별자를 추가 | 필수 | | CFBundleURLSchemes | 딥링크에 사용할 스키마 (커스텀 스키마) | 필수 | | |

2. TagWorks SDK 초기화 설정 및 딥링크를 통해 앱이 실행 될 때 딥링크 URL 처리

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // TagWorks instance 초기화 설정
    TagWorks *tagWorksInstance = TagWorks.sharedInstance;
    [tagWorksInstance setInstanceConfigWithSiteId:@"00,XXXXXXXX"
                                          ...
                                deeplinkServerUrl:[NSURL URLWithString:@"Deeplink Bridge Server URL"]];   // 딥링크 서버 URL 설정

    // #.딥링크로 앱이 실행될 때 실행 파라미터 전달
    NSURL *launchUrl = launchOptions[UIApplicationLaunchOptionsURLKey];
    if (launchUrl != nil) {
        [[TagWorks sharedInstance] launchWithOptionsWithUrl:launchUrl userInfo:nil];
    }
    ...
    ...
}

3. 앱이 실행 중인 상태에서 딥링크 URL 처리

// AppDelegate.m (iOS 12 이하)
- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [RCTLinkingManager application:application openURL:url options:options];
}

// 또는
// SceneDelegate.m (iOS 13 이상)
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
  if (URLContexts.count > 0) {
    UIOpenURLContext *urlContext = [URLContexts anyObject];
    [RCTLinkingManager application:[UIApplication sharedApplication]
                           openURL:urlContext.URL
                           options:urlContext.options];
  }
}

🔹 Android

1. 앱 내 스키마 등록 (App - AndroidManifest 설정)

<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 앱 내 딥링크 커스텀 스키마 설정 -->
        <data android:scheme="yourappscheme" />
    </intent-filter>
</activity>

| 파라미터 | 설명 | 필수 여부 | |---------|------|-----------| | android:scheme | 딥링크로 사용할 스키마 (커스텀 스키마) | 필수 | | android:host | 딥링크로 사용할 도메인 | 선택 |

2. TagWorksConfig 설정

TagWorksConfig config = new TagWorksConfig.Builder()
.setBaseUrl("서버 URL")
.setSiteId("발급받은 사이트 ID")
.setDeeplinkServerUrl("https://your-deeplink-server.com")   // 딥링크 서버 URL 설정
.build();

TagWorks.initializeSdk(this, config);

val config = TagWorksConfig.Builder()
    .setSiteId("서버 URL")
    .setBaseUrl("발급받은 사이트 ID")
    .setDeeplinkServerUrl("https://your-deeplink-server.com") // 딥링크 서버 URL 설정
    .build()

TagWorks.getInstance().initialize(context, config)

딥링크 처리 방법

딥링크 처리 (handleDeeplinkUrl)

앱이 실행되거나 앱이 실행중일 때 딥링크 정보를 처리하는 방법입니다.
React-Native에서는 Linking 모듈을 이용해 딥링크 URL을 수집합니다.
iOS에서는 딥링크 설정 시 Native에서 딥링크 URL을 전달하기에, React-Native 앱 내에서는 Android OS인 경우에만 handleDeferredDeeplink(), handleDeeplinkUrl() 메서드를 호출하여 SDK에 딥링크 URL을 전달합니다.
앱 내에서는 NativeEventEmitter를 이용한 addLandingListener()를 통해 딥링크 URI를 콜백으로 전달받아 유저를 설정한 목적지로 보낼 수 있습니다.
addLandingListener() 콜백으로 전달받는 파라미터에는 TagManager를 이용해 만들어진 딥링크 URL인지 여부를 판단하여 해당 파라미터에 같이 전달이 되며, TagManager 딥링크 여부 판별 후 딥링크 처리를 하실 수 있습니다.

useEffect(() => {
  // 1) 실행 중 유입 이벤트 리스너(먼저 등록!)
  // 리스너가 늦게 붙으면 sdk가 보낸 결과 이벤트를 받지 못함.
  const deeplinkLanding = TagWorksDeeplink.addLandingListener((e) => {
    console.log('[TagWorks] 딥링크 처리 후 콜백 호출됨.', e);

    if (e.isTagWorksDeeplink) {
      console.log('isTagWorks deeplink Listener: ', e.deeplinkURL);
      // navigateByUri(e.deeplinkURL);
    } else {
      console.log('Not isTagWorks deeplink Listener: ', e.deeplinkURL);
    }
  });

  // 앱이 실행 중일 때 딥링크 감지
  const subscription = Linking.addEventListener('url', ({ url }) => {
    console.log('[TagWorks] 앱 실행 중 딥링크 감지.');

    if (Platform.OS === 'android') {
      TagWorksDeeplink.handleDeeplinkUrl(url);
    }
  });

  // 앱이 cold start 된 경우 링크 가져오기
  Linking.getInitialURL().then((url) => {
    // console.log('cold start Deeplink received.');
    if (url) {
        console.log('Deeplink initialUrl', url);
        if (Platform.OS === 'android') {
          TagWorksDeeplink.handleDeeplinkUrl(url);
        }
    } else 
      if (Platform.OS === 'android') {
        console.log('안드로이드 Deferred Deeplink 체크');
        TagWorksDeeplink.handleDeferredDeeplink();
      }
  });
  
  return () => {
    deeplinkLanding();
    subscription.remove();
  };
}, []);

License

Apache 2.0

Made with Obzen Inc.