하나의 Clarity Project ID로 Android·iOS 통합 분석
마이크로소프트 Clarity는 SDK 초기화 때 같은 ID를 넣으면 Android와 iOS 앱을 Project ID 하나로 함께 수집한다. 설정 순서와 통합·분리 판단 기준, 마스킹 점검까지 정리했다.
목차
마이크로소프트 Clarity는 Project ID 하나로 Android와 iOS 앱을 같이 수집할 수 있다. 두 플랫폼의 SDK를 시작할 때 같은 ID 문자열을 넣으면 세션 기록과 히트맵이 한 대시보드로 모인다. 대신 데이터가 한곳에 섞이니, 플랫폼별 지표를 따로 봐야 한다면 프로젝트를 처음부터 나누는 쪽이 나을 때도 있다.
Project ID 하나를 두 플랫폼에 써도 되나
된다. Clarity에서 Project ID는 수집한 데이터가 쌓일 자리를 가리키는 식별자다. 마이크로소프트 공식 문서에 따르면 이 값은 Clarity 대시보드의 Settings → Overview 화면에서 확인한다. Android 빌드와 iOS 빌드가 같은 ID로 초기화되면 두 앱의 세션이 같은 프로젝트 안으로 들어온다. 앱을 새로 낼 때마다 프로젝트를 쪼갤 필요는 없다는 뜻이다.
한 서비스를 iOS와 Android로 함께 내는 경우가 여기에 잘 맞는다. 같은 화면, 같은 기능을 두 OS에서 제공하니 사용자 흐름을 한 판에서 비교하기 좋다. 결제 단계에서 이탈이 늘었다고 하자. 두 플랫폼을 한 프로젝트에서 보면 문제가 OS를 가리지 않고 공통으로 생기는지, 한쪽만의 문제인지 금방 감이 온다.
Android와 iOS에 같은 ID를 넣는 순서
설정 절차는 세 단계다 — 프로젝트 생성, SDK 추가, 초기화 코드 한 자리가 전부다. 먼저 Clarity 대시보드에서 프로젝트를 하나 만들고 Project ID를 확보한다. 그다음 Android 앱과 iOS 앱 양쪽에 Clarity SDK를 각각 추가하고, 앱이 켜지는 초기 시점에 SDK를 시작하면서 이 ID를 넘겨준다.
SDK 추가는 마이크로소프트 공식 문서 기준으로 Android가 mavenCentral 의존성 implementation 'com.microsoft.clarity:clarity:3.+' 한 줄이고(Jetpack Compose 앱은 별도의 clarity-compose 패키지를 쓴다), iOS는 Swift Package Manager에 https://github.com/microsoft/clarity-apps 패키지를 추가하거나 Podfile에 pod 'Clarity'를 넣는 방식이다.
실무에서는 ID 값을 코드에 직접 박지 말고 한곳에서 관리하길 권한다. Android라면 빌드 설정이나 리소스 값으로, iOS라면 빌드 구성이나 Info 설정 값으로 빼두면, 개발용과 운영용 프로젝트를 나눌 때도 코드를 건드리지 않고 ID만 바꿔 끼울 수 있다. 두 플랫폼이 같은 ID를 참조하도록 상수 이름을 맞춰 두면 나중에 헷갈릴 일도 줄어든다. Clarity 자체가 처음이라면 히트맵·세션 녹화 시작 글부터 보고 오는 편이 빠르다.
초기화는 앱 진입점에서 한 번만 하면 된다. Android는 Application 클래스가 시작하는 지점, iOS는 앱이 켜질 때 처음 호출되는 진입점이 자연스러운 자리다. 마이크로소프트 공식 문서도 시작 액티비티의 onCreate()에서 한 번만 호출하라고 안내하고, iOS는 AppDelegate의 didFinishLaunchingWithOptions, SwiftUI 앱이면 App의 init()을 초기화 자리로 제시한다 — 두 SDK 모두 초기화는 메인 스레드에서 불러야 한다. 초기화를 화면 곳곳에서 반복해 부르면 세션이 어긋나거나 중복 기록이 생길 수 있으니, 진입점 한 곳으로 모으는 편이 안전하다.
코드로는 양쪽 모두 두 줄 안팎이다. 아래 형태처럼 진입점에서 같은 ID를 넘긴다.
// Android — Application.onCreate()
val config = ClarityConfig("your-project-id")
Clarity.initialize(applicationContext, config)// iOS — 앱 시작 시점
let config = ClarityConfig(projectId: "your-project-id")
ClaritySDK.initialize(config: config)SDK 아티팩트 추가 방법과 최신 초기화 시그니처는 Clarity 공식 문서 기준으로 확인하는 편이 안전하다.
서로 다른 앱 식별자는 콤마로 구분해 함께 기입한다
한 프로젝트에 두 플랫폼을 붙일 때 실무에서 먼저 걸리는 지점이 앱 식별자 등록이다. Android 패키지명과 iOS 번들 ID는 서로 다른 값이라, 프로젝트 설정에 어느 쪽을 넣어야 할지 애매해진다. 이때는 두 식별자를 동시에 기입하되 콤마(,)로 구분하면 된다. Clarity 공식 GitHub 저장소의 이슈 답변에 따르면, 두 번들 ID를 콤마 문자로 구분해 입력하는 방식이 권장된다.
해당 이슈는 Android와 iOS의 번들 ID가 달라 프로젝트를 나눠야 하는지 묻는 React Native 앱 사례였고, 답변은 프로젝트 하나로 두 앱을 모두 받을 수 있다는 쪽이었다. 이렇게 식별자를 나란히 등록해 두면 Project ID는 그대로 하나만 유지되고, 앞서 본 대로 두 플랫폼의 세션이 한 대시보드로 모이는 구성이 성립한다.
합쳐서 볼 때와 나눠서 볼 때, 무엇이 다른가
합치면 관리 지점이 프로젝트 하나로 줄지만 대신 데이터가 섞인다. 여기서 판단이 갈린다. 두 플랫폼의 사용 패턴을 늘 함께 보고 싶다면 하나로 합치는 쪽이 관리가 간단하다. 프로젝트가 하나뿐이니 설정도 한 번, 확인할 화면도 한 곳이다.
반대로 iOS와 Android 지표를 자주 떼어 봐야 한다면 이야기가 달라진다. 갈라 보는 것 자체는 된다 — 마이크로소프트의 모바일 SDK 필터 문서에 따르면 사용자 정보 그룹에 운영체제(Operating system) 필터가 있고, 한 프로젝트에 여러 패키지를 연결한 경우를 위한 패키지 이름(Package Name) 커스텀 필터도 제공된다. 다만 확인할 때마다 필터를 걸거나 세그먼트로 저장해 두는 손이 따라붙는다. 릴리스 주기가 서로 다르거나, 한쪽 OS에서만 특정 실험을 돌리는 팀이라면 분리가 더 어울린다.
| 기준 | 프로젝트 통합(ID 하나) | 프로젝트 분리(ID 둘) |
|---|---|---|
| 설정·확인 지점 | 프로젝트 1개, 대시보드 1곳 | 프로젝트 2개, 대시보드 2곳 |
| 플랫폼별 분석 | 운영체제·Package Name 필터나 세그먼트를 걸어서 | 기본 상태가 이미 분리 |
| 어울리는 팀 | 한 서비스를 두 OS로 함께 내는 팀 | 릴리스 주기·실험이 OS별로 다른 팀 |
정답이 하나로 정해져 있지는 않다. '한 서비스를 두 OS로 낸다'에 가까우면 통합, '사실상 두 팀이 각자 앱을 굴린다'에 가까우면 분리. 이 기준으로 먼저 갈라 보면 결정이 한결 쉬워진다.
설정 전에 점검할 것
SDK 버전과 지원 범위를 먼저 확인하자. 지원 하한이 생각보다 높다 — 마이크로소프트 공식 문서에 따르면 Android는 API 레벨 19~28에서 빌드는 성공하지만 데이터가 Clarity로 전송되지 않고, iOS도 13·14 버전에서는 앱이 빌드·실행돼도 데이터가 전송되지 않는다. 쓰려는 SDK 버전이 어떤 OS 버전과 기능까지 지원하는지는 공식 문서의 플랫폼 지원 매트릭스에서 짚어 두는 게 좋다. 버전에 따라 제공되는 기능이 다를 수 있다.
개인정보 처리도 빼놓을 수 없다. 세션 기록 도구는 화면에 뜬 값을 그대로 담을 수 있어서, 로그인 정보나 결제 화면처럼 민감한 입력이 노출되지 않도록 마스킹 설정을 반드시 점검해야 한다. 이 설정은 플랫폼마다 따로 잡아 줘야 하는 경우가 많다. Android는 Clarity.maskView(view)를 해당 뷰를 올리는 액티비티의 onCreate()에서, iOS는 ClaritySDK.maskView(_:)를 viewDidLoad()에서 부른다. 특히 SwiftUI는 마이크로소프트 공식 문서가 입력 필드 강제 마스킹을 아직 지원하지 않는다고 명시하고 있어, clarityMask() 수정자를 입력 필드마다 개별로 붙여야 한다. ID만 같으면 마스킹까지 저절로 맞춰진다고 넘겨짚지 말자.
마지막으로 연동 직후에는 두 플랫폼에서 각각 테스트 세션을 만들어 대시보드에 실제로 들어오는지 눈으로 확인하는 절차를 넣자. 이때 로그 레벨을 기본값 None에서 Verbose로 올리면 초기화 오류가 로그에 잡힌다. 마이크로소프트 공식 문서에 따르면 완결된 세션이 대시보드에 나타나기까지 최대 2시간이 걸릴 수 있고, 진행 중 세션은 실시간 보기로 먼저 확인할 수 있다 — 데이터가 안 보인다고 곧바로 설정 오류로 단정할 일은 아니라는 뜻이다. ID 오타 하나로 데이터가 엉뚱한 프로젝트에 쌓이거나 아예 안 들어오는 일이 생길 수 있다. 초기화 위치, ID 값, 네트워크 권한 이 세 가지만 훑어도 초기 문제 대부분은 걸러진다.