아직 열리지 않는 데이터를 위한 카드
허브 대시보드에 카드를 하나 추가했습니다. 봇이 앱으로 보낸 유입을 UTM 소스별 세션 수로 보여 주는 카드이고, 데이터는 GA4 Data API에서 가져옵니다. 변경은 hub.py 한 파일에 41줄을 더한 것이 전부입니다.
다만 배포 시점에 이 카드가 읽을 수 있는 데이터는 하나도 없었습니다. GA4 속성 ID와 서비스 계정 크리덴셜을 아직 넣지 않았기 때문입니다. 커밋 메시지에도 '파이프 선배포'라고 적었습니다. 데이터가 흐르는 길만 먼저 깔아 두고, 열쇠는 나중에 꽂겠다는 뜻이었습니다.
이 순서에는 함정이 하나 있습니다. 열쇠가 없는 카드가 무엇을 보여 줄지 정하지 않으면, 화면에는 빈칸이나 0이 뜨기 쉽습니다. 그리고 대시보드에서 0은 "봇이 앱으로 사람을 하나도 못 보냈다"는 뜻으로 읽힙니다.
당신의 대시보드에 있는 카드 중에, 지금 0을 보여 주는 카드가 '실제로 0'인지 '아직 연결이 안 됨'인지 화면만 보고 구분할 수 있는 카드가 몇 개나 되나요?
0과 '모름'은 다른 값입니다
유입 카드에서 0은 의사결정에 바로 쓰이는 숫자입니다. 이 채널은 효과가 없다, 봇 문구를 바꿔야 한다, 아예 접어야 한다는 판단이 0 하나에서 나올 수 있습니다. 그런데 크리덴셜이 없어서 생긴 0이라면, 그 판단은 측정한 적도 없는 것을 근거로 내린 결론이 됩니다.
반대로 에러를 던지며 카드가 깨지는 것도 좋은 선택은 아니었습니다. 아직 설정하지 않은 것은 의도된 상태였고, 그 때문에 허브 전체가 빨갛게 보일 이유는 없었습니다.
그래서 필요한 것은 세 번째 상태였습니다. 숫자도 아니고 에러도 아닌 "설정 대기"입니다.
당신이라면 크리덴셜이 들어올 때까지 카드 배포를 미루시겠습니까, 아니면 먼저 배포하고 빈 상태를 따로 정의하시겠습니까?
제가 고른 방식: 환경변수 게이트와 fail-closed 셀프체크
저는 먼저 배포하는 쪽을 골랐고, 새 패턴을 만들지 않았습니다. 허브에는 이미 같은 방식으로 동작하는 다른 카드가 있었고, 그 env 게이트 패턴을 그대로 가져왔습니다.
동작은 단순합니다. GA4_PROPERTY_ID와 서비스 계정 크리덴셜이 둘 다 있으면 카드가 활성화되어 GA4 Data API를 호출합니다. 하나라도 없으면 API를 부르지 않고 "설정 대기" 폴백을 보여 줍니다.
여기에 셀프체크를 하나 붙였습니다. 미설정 상태에서는 fail-closed, 즉 닫힌 쪽으로 떨어지도록 확인하는 검사입니다. 설정이 비어 있는데 카드가 숫자 모드로 들어가는 일, 다시 말해 빈 설정이 0으로 둔갑하는 일을 막는 것이 목적입니다.
돌아보면 41줄 대부분은 숫자를 그리는 코드보다, 숫자를 그리면 안 되는 상황을 정의하는 데 쓰였습니다.
자가진단 체크리스트
- 외부 API에 의존하는 대시보드 카드마다 '크리덴셜 없음' 상태가 0이나 빈칸이 아닌 별도 문구로 표시되나요?
- 설정이 비어 있을 때 카드가 숫자 모드로 들어가지 않는다는 것을 확인하는 검사(셀프체크든 테스트든)가 있나요?
- 같은 종류의 게이트가 이미 코드베이스에 있다면, 새로 만들지 않고 그 패턴을 재사용했나요?
솔직한 부분
이 글의 근거는 카드를 추가한 커밋 하나뿐입니다. 이후에 크리덴셜을 실제로 넣었는지, 카드가 활성화된 뒤 어떤 숫자가 나왔는지, 봇에서 앱으로 가는 UTM 유입이 의미 있는 규모였는지는 이 소재에 없어서 쓸 수 없습니다. 셀프체크가 미설정 상태를 막는다는 것은 확인했지만, 크리덴셜은 있는데 권한이 부족하거나 속성 ID가 틀린 경우에도 카드가 '모름'으로 정직하게 떨어지는지는 이 커밋만으로는 알 수 없습니다. 파이프를 먼저 까는 방식이 옳았는지도 열쇠를 꽂은 뒤에야 판단할 수 있습니다.