# Firebase 이벤트 전송

Firebase Analytics 표준 이벤트와 커스텀 이벤트를 logEvent로 전송하는 규칙과 파라미터 명명 기준.

- 카테고리: Firebase
- 소요 시간: 약 8분
- 난이도: 중간
- 업데이트: 2026.06.16
- 원문: /wiki/playbook/firebase-checklist/how-to-send-firebase-events

## 목차

- [이 문서의 목적](#purpose)
- [1단계 · logEvent 구조](#step-1)
- [2단계 · 이벤트 설계](#step-2)
- [3단계 · Android 전송 코드](#step-3)
- [4단계 · iOS 전송 코드](#step-4)
- [5단계 · 파라미터 규칙](#step-5)
- [6단계 · 전송 후 확인](#step-6)
- [참고 링크](#references)
- [자주 묻는 질문](#faq)

이 문서는 Android/iOS 앱에서 Firebase Analytics 이벤트를 Native SDK로 전송하는 기본 패턴을 정리합니다. 앱 화면에서 발생한 행동은 Android의 `FirebaseAnalytics.logEvent`, iOS의`Analytics.logEvent`로 직접 전송합니다. WebView 안에서 발생한 JavaScript 이벤트만 별도[WebView bridge](/wiki/playbook/firebase-checklist/how-to-connect-firebase-webview-events)를 통해 Native로 넘깁니다.

> **이 문서 핵심**
>
> - Firebase SDK 초기화가 끝나 있고 앱에서 이벤트가 발생하는 지점을 알고 있어야 합니다.
>
> - 이벤트 이름과 파라미터 이름은 Android/iOS에서 동일하게 맞춥니다.
>
> - 로그인, 검색, 콘텐츠 선택, 커스텀 행동 같은 범용 앱 이벤트를 GA4에서 확인할 수 있습니다.

## 1단계. Native SDK logEvent 구조 확인

Firebase 이벤트는 **이벤트 이름**과 **파라미터 묶음**으로 구성됩니다. Android는 `Bundle`, iOS는 `[String: Any]` 딕셔너리를 사용합니다.

![Android 앱과 iOS 앱에서 logEvent 호출이 Firebase SDK를 거쳐 GA4 보고서로 직접 전송되는 구조 이미지. WebView 브릿지 없음 문구와 직접 전송 영역이 강조되어 있다.](/wiki-assets/playbook/how-to-send-firebase-events/01-ga4-screen-view-report.png)

> **구조.** Native 화면 이벤트는 WebView bridge 없이 각 플랫폼 SDK에서 직접 보냅니다.

**Android · login 이벤트 전송**
```kotlin
import android.os.Bundle
import com.google.firebase.analytics.FirebaseAnalytics

val analytics = FirebaseAnalytics.getInstance(context)

analytics.logEvent(FirebaseAnalytics.Event.LOGIN, Bundle().apply {
    putString(FirebaseAnalytics.Param.METHOD, "email")
})
```

**iOS · login 이벤트 전송**
```swift
import FirebaseAnalytics

Analytics.logEvent(AnalyticsEventLogin, parameters: [
    AnalyticsParameterMethod: "email"
])
```

> **주의**
>
> 같은 행동은 모든 플랫폼에서 같은 이벤트명과 같은 파라미터명으로 보냅니다. `login`과`Login`은 GA4에서 서로 다른 이벤트로 집계됩니다.

## 2단계. 이벤트 이름과 파라미터 설계

먼저 앱의 주요 행동을 GA4 권장 이벤트에 매핑합니다. 표준 이벤트로 표현하기 어려운 행동만 커스텀 이벤트로 둡니다.

| 상황 | 권장 이벤트 | 주요 파라미터 |
| --- | --- | --- |
| 로그인 | `login` | `method` |
| 회원가입 | `sign_up` | `method` |
| 검색 | `search` | `search_term` |
| 콘텐츠/버튼 선택 | `select_content` | `content_type`, `item_id` |
| 서비스 고유 행동 | 커스텀 이벤트 | 행동을 설명하는 커스텀 파라미터 |

> **정보**
>
> 이벤트명은 행동이 드러나는 `snake_case`로 고정합니다. `click`, `success`,`complete`처럼 단독으로 의미가 약한 이름은 운영 리포트에서 해석하기 어렵습니다.

## 3단계. Android 전송 코드 작성

이벤트 호출을 화면마다 직접 흩뿌리지 말고, 앱 안에 작은 전송 유틸을 만들어 같은 규칙으로 호출합니다. 아래 예시는 로그인, 검색, 콘텐츠 선택, 커스텀 행동을 다룹니다.

**Android · AppAnalytics.kt 전체 예시**
```kotlin
import android.os.Bundle
import com.google.firebase.analytics.FirebaseAnalytics

class AppAnalytics(
    private val analytics: FirebaseAnalytics
) {
    fun logLogin(method: String) {
        analytics.logEvent(FirebaseAnalytics.Event.LOGIN, Bundle().apply {
            putString(FirebaseAnalytics.Param.METHOD, method)
        })
    }

    fun logSignUp(method: String) {
        analytics.logEvent(FirebaseAnalytics.Event.SIGN_UP, Bundle().apply {
            putString(FirebaseAnalytics.Param.METHOD, method)
        })
    }

    fun logSearch(searchTerm: String) {
        analytics.logEvent(FirebaseAnalytics.Event.SEARCH, Bundle().apply {
            putString(FirebaseAnalytics.Param.SEARCH_TERM, searchTerm)
        })
    }

    fun logSelectContent(contentType: String, itemId: String) {
        analytics.logEvent(FirebaseAnalytics.Event.SELECT_CONTENT, Bundle().apply {
            putString(FirebaseAnalytics.Param.CONTENT_TYPE, contentType)
            putString(FirebaseAnalytics.Param.ITEM_ID, itemId)
        })
    }

    fun logCustomAction(actionName: String, parameters: Bundle = Bundle()) {
        analytics.logEvent(actionName, parameters)
    }
}
```

**Android · 호출 예시**
```kotlin
val appAnalytics = AppAnalytics(FirebaseAnalytics.getInstance(context))

appAnalytics.logLogin(method = "email")
appAnalytics.logSearch(searchTerm = "running shoes")
appAnalytics.logSelectContent(
    contentType = "button",
    itemId = "home_cta"
)

appAnalytics.logCustomAction("select_feature", Bundle().apply {
    putString("feature_id", "FEATURE_001")
    putString("feature_name", "Sample Feature")
    putString("entry_point", "home")
})
```

## 4단계. iOS 전송 코드 작성

iOS도 Android와 같은 이벤트명·파라미터명을 사용합니다. 플랫폼 코드 스타일은 달라도 GA4로 들어가는 이름은 동일해야 하나의 리포트에서 비교할 수 있습니다.

**iOS · AppAnalytics.swift 전체 예시**
```swift
import FirebaseAnalytics

final class AppAnalytics {
    func logLogin(method: String) {
        Analytics.logEvent(AnalyticsEventLogin, parameters: [
            AnalyticsParameterMethod: method
        ])
    }

    func logSignUp(method: String) {
        Analytics.logEvent(AnalyticsEventSignUp, parameters: [
            AnalyticsParameterMethod: method
        ])
    }

    func logSearch(searchTerm: String) {
        Analytics.logEvent(AnalyticsEventSearch, parameters: [
            AnalyticsParameterSearchTerm: searchTerm
        ])
    }

    func logSelectContent(contentType: String, itemId: String) {
        Analytics.logEvent(AnalyticsEventSelectContent, parameters: [
            AnalyticsParameterContentType: contentType,
            AnalyticsParameterItemID: itemId
        ])
    }

    func logCustomAction(_ actionName: String, parameters: [String: Any]? = nil) {
        Analytics.logEvent(actionName, parameters: parameters)
    }
}
```

**iOS · 호출 예시**
```swift
let appAnalytics = AppAnalytics()

appAnalytics.logLogin(method: "email")
appAnalytics.logSearch(searchTerm: "running shoes")
appAnalytics.logSelectContent(
    contentType: "button",
    itemId: "home_cta"
)

appAnalytics.logCustomAction("select_feature", parameters: [
    "feature_id": "FEATURE_001",
    "feature_name": "Sample Feature",
    "entry_point": "home"
])
```

## 5단계. 파라미터 타입과 맞춤 측정기준 정리

파라미터는 보고서에서 비교 가능한 형태로 보내야 합니다. 문자열로 비교할 값은 문자열, 수량/금액처럼 계산할 값은 숫자로 보냅니다. 표준 파라미터가 아닌 값은 GA4 맞춤 측정기준으로 등록해야 보고서에서 사용할 수 있습니다.

| 종류 | 예시 | 전송 타입 |
| --- | --- | --- |
| 분류/ID | `method`, `content_type`, `item_id`, `feature_id` | 문자열 |
| 건수/순서 | `step`, `result_count` | 정수 |
| 금액/비율 | `value`, `discount_rate` | 실수 |
| 참/거짓 | `is_first_use` | `true`/`false` 문자열 또는 `1`/`0` 숫자 |

**GA4 UI 등록 경로**
```text
관리 > 데이터 표시 > 맞춤 정의 > 맞춤 측정기준 만들기

예시 이벤트 범위 파라미터:
feature_id, feature_name, entry_point, content_type, plan_type
```

> **주의**
>
> 맞춤 측정기준은 소급 적용되지 않습니다. 등록 전에 보낸 커스텀 파라미터는 나중에 보고서에서 조회해도`(not set)`으로 남을 수 있으므로, 등록 후 이벤트를 다시 보내 확인합니다.

> **정보**
>
> 회원 등급, 로그인 상태, 사용자 유형처럼 특정 이벤트가 아니라 사용자에게 붙는 상태값은 이벤트 파라미터가 아니라[User Property](/wiki/playbook/firebase-checklist/how-to-set-firebase-user-properties)로 설정합니다.

## 6단계. 전송 후 DebugView에서 확인

구현 후에는 앱에서 이벤트를 발생시키고 DebugView에서 이벤트 이름과 파라미터가 의도대로 들어오는지 확인합니다. 보고서 반영에는 시간이 걸릴 수 있으므로 개발 중 1차 확인은 DebugView로 진행합니다.

![GA4 DebugView에서 select_content 이벤트를 선택해 content_type과 item_id 파라미터를 확인하는 실제 화면.](/wiki-assets/playbook/how-to-send-firebase-events/02-debugview-event-parameters.png)

> **화면.** DebugView에서 이벤트명과 파라미터 키·값이 의도대로 들어왔는지 확인합니다.

> **완료**
>
> DebugView에서 이벤트가 보이면 다음 단계는 [연동 검증](/wiki/playbook/firebase-checklist/how-to-verify-firebase-integration)입니다. 디버그 기기, 실시간 보고서, 다음날 이벤트 보고서를 순서대로 확인합니다.

## 참고 링크

- [이벤트 로깅(Android)](https://firebase.google.com/docs/analytics/events?platform=android)
- [이벤트 로깅(iOS)](https://firebase.google.com/docs/analytics/events?platform=ios)
- [GA4 권장 이벤트 레퍼런스](https://developers.google.com/analytics/devguides/collection/ga4/reference/events)
- [WebView 이벤트 연동](/wiki/playbook/firebase-checklist/how-to-connect-firebase-webview-events)
- [Firebase User Property 설정](/wiki/playbook/firebase-checklist/how-to-set-firebase-user-properties)

## 자주 묻는 질문

### WebView 화면에서 발생한 이벤트도 이 코드로 보내나요?

최종 전송은 Native SDK가 담당합니다. 다만 WebView 안의 JavaScript 이벤트는 먼저 WebView bridge로 Native에 넘긴 뒤, Native bridge 내부에서 이 문서와 같은 방식으로 `logEvent`를 호출합니다.

### 표준 이벤트와 커스텀 이벤트 중 무엇을 써야 하나요?

GA4 권장 이벤트로 표현할 수 있으면 표준 이벤트를 먼저 사용합니다. 표준 이벤트로 의미가 맞지 않는 서비스 고유 행동만 커스텀 이벤트로 만듭니다.

## Navigation

- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)

### Firebase

- [Firebase](/wiki/playbook/firebase-checklist)
- [Firebase 프로젝트·앱 등록](/wiki/playbook/firebase-checklist/how-to-create-firebase-app)
- [Firebase SDK 초기화](/wiki/playbook/firebase-checklist/how-to-initialize-firebase-sdk)
- [Firebase WebView 이벤트 연동](/wiki/playbook/firebase-checklist/how-to-connect-firebase-webview-events)
- [Firebase 이벤트 전송](/wiki/playbook/firebase-checklist/how-to-send-firebase-events) (현재 문서)
- [Firebase User ID·User Property 설정](/wiki/playbook/firebase-checklist/how-to-set-firebase-user-properties)
- [Firebase 연동 검증](/wiki/playbook/firebase-checklist/how-to-verify-firebase-integration)