사용자 정의 태그 사용¶

이 문서에서는 SDK, RUM, Log 전역 태그, 개별 이벤트 속성 및 사용자 정보의 사용 범위를 설명합니다.

전역 태그 유형¶

정적 전역 태그¶

전역 태그는 초기화 시 설정됩니다.

guanceSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    globalContext: {
      game_channel: 'app-store',
      build_flavor: 'release',
    },
  },
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    globalContext: {
      game_mode: 'ranked',
    },
  },
  logger: {
    enableCustomLog: true,
    globalContext: {
      log_source: 'cocos',
    },
  },
});

전역 태그 값은 반드시 문자열이어야 합니다. 숫자나 불리언 값을 표현해야 하는 경우 비즈니스 측에서 먼저 문자열로 변환하세요.

개별 이벤트 속성¶

RUM 및 Log 수동 API의 attributes는 다음을 지원합니다.

• 문자열
• 숫자
• 불리언
• null
• 위 유형으로 구성된 배열
• JSON 객체

guanceSdk.rum.addAction('Purchase', 'click', {
  product_id: 'sword-001',
  price: 9.9,
  success: true,
  tags: ['shop', 'weapon'],
});

guanceSdk.logger.log('purchase completed', 'info', {
  product_id: 'sword-001',
  result: {
    currency: 'CNY',
    amount: 9.9,
  },
});

함수, Cocos Node, Camera, 순환 참조 객체 또는 JSON으로 직렬화할 수 없는 기타 값을 전달하지 마세요.

사용자 정보¶

사용자가 로그인한 후 바인딩합니다.

guanceSdk.mobile.bindUser({
  userId: 'user-123',
  userName: '玩家昵称',
  userEmail: 'player@example.com',
  extra: {
    membership: 'gold',
  },
});

사용자가 로그아웃한 후 바인딩을 해제합니다.

guanceSdk.mobile.unbindUser();

userId는 빈 문자열일 수 없습니다. extra는 문자열 키-값만 지원합니다.

동적 태그¶

현재 Cocos API는 런타임에 전역 태그를 추가하거나 삭제하는 방법을 제공하지 않습니다. 초기화 후 변경되는 비즈니스 정보는 다음 방법을 선택할 수 있습니다.

1. 개별 이벤트 attributes로 전달
2. 로컬에 저장하고 다음 앱 시작 시 globalContext에 추가
3. 사용자 신원이 변경될 때 bindUser() 또는 unbindUser() 호출

guanceSdk.start()를 반복 호출하여 태그를 업데이트하지 마세요. 반복 초기화는 중복 리스너 또는 Native SDK 상태 충돌을 유발할 수 있습니다.

명명 및 충돌¶

• 비즈니스 태그에 프로젝트 접두사를 붙이는 것이 좋습니다. 예: game_region, game_channel.
• RUM 표준 필드(예: app_id, session_id, view_id, service, env)를 덮어쓰지 마세요.
• sdk_package_cocos를 사용하지 마세요. 이 필드는 Cocos SDK가 현재 npm 패키지 버전을 기록하는 데 사용합니다.
• track_id는 분산 추적 시나리오에 사용되며, 명확히 필요한 경우에만 사용하세요.
• 사용자 정의 필드가 Native SDK 기본 제공 필드와 충돌하는 경우 최종 값이 기본 제공 필드로 덮어써질 수 있습니다.

모든 태그는 최소화 원칙을 따라야 하며, 사용자 비밀번호, Token, 전체 주민등록번호 등 민감한 내용을 포함하지 않도록 주의하세요. 자세한 내용은 데이터 및 개인정보 보호를 참조하세요.