# Meta Ads 통합

<Aside type="caution" icon="setting" title="개발자 지원 필요">
 통합을 설정하려면 개발팀의 도움이 필요합니다. 이 가이드를 개발팀과 공유해주세요.
</Aside>

[Meta Ads](https://www.facebook.com/business/ads) 통합을 사용하면 Pushwoosh 오디언스를 Meta 광고 계정과 동기화할 수 있습니다. 이를 사용하여 광고 캠페인에서 사용자를 타겟팅하거나 제외하고, 고객 여정에 유료 광고를 또 다른 채널로 추가할 수 있습니다.

## 사용 사례

이 통합을 사용하여 다음을 수행할 수 있습니다:

* 여러 채널에서 가치가 높은 사용자를 타겟팅하여 구매 또는 참여를 늘립니다.
* 다른 채널에서 반응이 적은 사용자를 리타겟팅합니다.
* 충성도 높은 고객이 불필요한 광고를 받지 않도록 제외 오디언스를 구축합니다.


## 전제 조건
Meta Ads를 연결하기 전에 다음을 확인하세요:

* Pushwoosh 계정에서 **Admin** 역할이 있어야 합니다. 역할 및 권한 작동 방식에 대한 자세한 내용은 [사용자 접근 및 권한 관리](/ko/product/account-management-and-security/multi-login-accounts/#creating-and-managing-roles-also-known-as-groups)를 참조하세요.
* 브랜드의 Facebook 자산(광고 계정, 페이지, 앱 포함)을 관리하기 위해 [**Facebook Business Manager**](https://www.facebook.com/business/tools/business-manager)가 설정되어 있어야 합니다.
* Business Manager에 연결된 활성 [**Facebook 광고 계정**](https://www.facebook.com/business/tools/ads-manager)이 있어야 합니다.
* Facebook Business Manager 관리자가 Pushwoosh와 함께 사용할 광고 계정에 대해 **캠페인 관리** 또는 **광고 계정 관리** 권한을 부여해야 합니다.
* 해당 광고 계정에 대한 광고 계정 이용 약관에 동의해야 합니다.
* Pushwoosh와 함께 사용할 Facebook 광고 계정에 대한 [**Facebook의 맞춤 타겟 약관**](https://business.facebook.com/legal/terms/customaudience)에 동의해야 합니다.

## Pushwoosh에서 Meta Ads 설정하기

1. Pushwoosh에서 **Settings** > **3rd party integrations**로 이동합니다.

2. Meta Ads 카드에서 **Login page**를 클릭합니다.

<img src="/integrations-meta-ads-integration-1.webp" alt="Meta Ads 카드가 있는 타사 통합 페이지에 Configuration, Setup guide, Login page 링크가 표시됨"/>

3. Meta 계정에 로그인한 후 **Continue**를 클릭합니다.

4. 연결하려는 광고 계정을 선택합니다.
<img src="/integrations-meta-ads-integration-6.webp" alt="연결된 통합에 대한 비즈니스 액세스 옵션을 선택하는 Meta 화면" width="480" />

5. 광고 계정 및 비즈니스 액세스에 대해 요청된 권한을 검토합니다.

6. **Save**를 클릭합니다. 그러면 Meta에서 계정이 연결되었다는 확인 메시지를 표시합니다.

### 연결 상태 검토


설정 후 Pushwoosh의 **Meta Ads** 페이지로 리디렉션됩니다.

<img src="/integrations-meta-ads-integration-8.webp" alt="연결됨 배지, 비즈니스 계정 열이 있는 광고 계정 테이블, 헤더 작업 및 Meta와 오디언스 동기화 방법이 있는 Pushwoosh Meta Ads 페이지" />

광고 계정 테이블에는 각 연결된 계정이 다음과 같이 나열됩니다:

* **광고 계정 이름**
* **비즈니스 계정**
* **ID**

행 끝에 있는 세 개의 점을 열고 **광고 계정 제거**를 선택하여 Pushwoosh 목록에서 해당 광고 계정을 삭제합니다.

### 연결된 광고 계정 관리

**Meta Ads** 페이지에서 **Manage accounts**를 클릭하여 대화 상자를 엽니다. 각 행의 토글을 사용하여 통합에서 해당 광고 계정을 포함하거나 제외합니다.
**Apply**를 클릭하여 변경 사항을 저장하거나 **Cancel**을 클릭하여 저장하지 않고 닫습니다.

목록 보기를 조정하려면:

* **Show only connected**를 켜거나 꺼서 표시되는 행을 제한합니다.
* **Search by name or id...**에 입력하여 목록에서 계정을 찾습니다.

<img src="/integrations-meta-ads-integration-4.webp" alt="연결된 항목만 표시 토글, 이름 또는 ID로 검색, 연결됨 또는 연결 끊김 배지가 있는 행 토글, 취소 및 적용이 있는 광고 계정 관리 대화 상자" />



### 프로젝트 태그를 Meta 필드에 매핑하기

사용자 속성을 매핑하면 Pushwoosh에 어떤 Meta 사용자 속성이 프로젝트의 어떤 **태그 이름** 필드를 업데이트해야 하는지 알려줄 수 있습니다. 이렇게 하면 Meta에서 데이터가 올 때 예상한 위치에 저장됩니다.

<Aside type="note">
오디언스 동기화를 위해 Pushwoosh는 프로필에 존재하는 정보에 따라 **이메일**, **전화번호** 또는 **MADID** 중 사용자당 하나의 식별자를 항상 전송합니다. Meta가 위의 식별자 외에 **추가적인** 사용자 속성을 수신하기를 원할 때 매핑을 구성하세요.
</Aside>

1. **Meta Ads** 페이지에서 **Map user data**를 클릭합니다.

2. 왼쪽 열의 각 **Facebook 필드**에 대해 오른쪽 컨트롤에서 프로젝트의 **태그 이름**을 선택합니다.
필요한 행만 매핑하세요.

<img src="/integrations-meta-ads-integration-3.webp" alt="Facebook 필드 및 태그 이름 열, 덮어쓰기 확인란, 취소 및 저장이 있는 프로젝트 태그를 Meta 필드에 매핑 모달" width="480" />

<Aside type="note" title="자동으로 매핑된 필드">
Pushwoosh는 다음 필드를 자동으로 매핑합니다. **프로젝트 태그를 Meta 필드에 매핑**에서 설정하지 않습니다:

* **이메일**
* **전화번호**
* **MADID**
</Aside>
3. **Save**를 클릭하여 매핑을 적용하거나 **Cancel**을 클릭하여 저장하지 않고 닫습니다.

## SDK에서 MADID 수집 활성화하기

Meta Ads는 모바일 SDK를 통해 수집된 기기 식별자(MADID)를 사용하여 사용자를 매칭합니다.
Pushwoosh SDK는 광고 식별자(Android의 GAID, iOS의 IDFA)를 자동으로 수집하지 않습니다.
두 플랫폼 모두 식별자를 읽기 전에 명시적인 사용자 동의가 필요합니다.
애플리케이션에서 사용자 동의를 요청하고, 허용될 때 식별자를 읽어 SDK에 전달하세요.

<Tabs syncKey="maid-sdk">
<TabItem label="Android">

**1. 종속성 추가**

```groovy
implementation 'com.google.android.gms:play-services-ads-identifier:...'
```

**2. AD_ID 권한 선언 (targetSdk ≥ 33에 필요)**

`AndroidManifest.xml`에 다음을 추가합니다:

```xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
```

<Aside type="caution">
Android 13 이상에서 이 권한이 없으면 `AdvertisingIdClient.getAdvertisingIdInfo()`는 조용히 0으로 채워진 UUID(`00000000-0000-0000-0000-000000000000`)를 반환합니다. Pushwoosh SDK는 이를 `null`로 정규화하므로 MADID가 서버로 전송되지 않고 Meta 오디언스 매칭이 작동하지 않습니다.
</Aside>

**3. GAID를 검색하여 SDK에 전달**

`getAdvertisingIdInfo`는 백그라운드 스레드에서 호출해야 합니다:

```java

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

```

백엔드에 저장된 값을 지우려면 `null` 또는 빈 문자열을 전달합니다:

```java
Pushwoosh.getInstance().setAdvertisingId(null);
```

**동작 참고 사항:**

- 마지막 성공적인 호출 이후 값이 변경되지 않은 경우 네트워크 요청이 이루어지지 않습니다.
- 네트워크 요청이 실패하면 다음 앱 실행 시 재시도합니다.
- `Pushwoosh.stopCommunication()`이 활성화되어 있으면 호출이 무시됩니다.
- 0 UUID(`00000000-0000-0000-0000-000000000000`)는 `null`과 동일하게 처리됩니다 — 저장된 MADID가 백엔드에서 지워집니다.

</TabItem>
<TabItem label="iOS">

**1. `Info.plist`에 사용 설명 추가**

Apple은 ATT 권한 대화 상자를 표시하기 전에 이 키를 요구합니다:

```xml
<key>NSUserTrackingUsageDescription</key>
<string>We use your advertising identifier to show you relevant ads.</string>
```

**2. 개인정보처리방침 매니페스트에 추적 도메인 선언**

앱이 추적을 위해 IDFA를 사용하는 경우, Apple은 [개인정보처리방침 매니페스트](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files)(`PrivacyInfo.xcprivacy`)에 추적 데이터를 수신하는 도메인을 나열하도록 요구합니다. 전체 요구 사항은 [TN3182](https://developer.apple.com/documentation/technotes/tn3182-adding-privacy-tracking-keys-to-your-privacy-manifest)를 참조하세요.

`NSPrivacyTracking`을 `true`로 설정하고 Pushwoosh 추적 도메인을 `NSPrivacyTrackingDomains`에 추가합니다:

```xml
<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>
```

<Aside type="note">
사용자가 ATT 권한을 부여하지 않은 경우, iOS는 `NSPrivacyTrackingDomains`에 나열된 모든 도메인에 대한 네트워크 요청을 차단합니다. 코드가 무엇을 하든 MADID는 전송되지 않습니다.
</Aside>

**3. 추적 승인을 요청하고 IDFA를 SDK에 전달**

`ATTrackingManager`는 iOS 14 이상이 필요합니다. 배포 대상이 iOS 14 미만인 경우, 호출을 가용성 확인으로 래핑하세요.

Pushwoosh SDK는 `ATTrackingManager`를 호출하지 않습니다. 애플리케이션에서 추적 승인을 요청한 다음 결과를 SDK에 전달합니다:

```swift
import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}
```


백엔드에 저장된 값을 지우려면 `nil` 또는 빈 문자열을 전달합니다:

```swift
Pushwoosh.configure.setAdvertisingId(nil)
```

**동작 참고 사항:**

- 마지막 성공적인 호출 이후 값이 변경되지 않은 경우 네트워크 요청이 이루어지지 않습니다.
- 네트워크 요청이 실패하면 다음 앱 실행 시 `setAdvertisingId`를 다시 호출합니다.
- `Pushwoosh_ALLOW_SERVER_COMMUNICATION`이 비활성화되어 있으면 호출이 무시됩니다.
- 0 UUID(`00000000-0000-0000-0000-000000000000`)는 `nil` 또는 빈 문자열과 동일하게 처리됩니다 — 저장된 MADID가 백엔드에서 지워집니다.

> 앱의 메인 UI 흐름에서 `requestTrackingAuthorization`을 호출하세요. Apple은 실행 직후가 아니라 자체 설명 화면을 표시한 후에 이 작업을 수행할 것을 권장합니다.

</TabItem>
</Tabs>

### 작동 방식

`setAdvertisingId`를 호출하면 SDK는 해당 값을 앱 코드 및 기기 하드웨어 ID와 함께 `madid` 필드로 Pushwoosh 추적 엔드포인트에 전송합니다. Pushwoosh는 이 식별자를 사용하여 기기 기록을 동기화를 위한 Meta Ads 오디언스와 매칭합니다.


## Journey에서 오디언스 동기화하기

**Journey Builder**의 **오디언스 동기화** 지점은 Journey를 Meta 맞춤 타겟에 연결합니다. 사용자가 해당 지점에 도달할 때마다 Pushwoosh는 Meta에 해당 사용자를 오디언스에 추가하거나 제거하도록 요청합니다.

예를 들어, 이미 등록한 사용자에게 웨비나 광고 표시를 중단하여 더 이상 볼 필요가 없는 사람들에게 광고비를 낭비하지 않도록 할 수 있습니다.

오디언스 동기화를 구성하려면:

1. [**Journey Builder**](/ko/product/customer-journey/pushwoosh-journey-overview/)를 엽니다.

2. [**오디언스 기반 진입**](/ko/product/customer-journey/journey-elements/entry-elements/audience-based-entry/)을 추가합니다. **오디언스 소스**에서 이 Journey에 진입할 대상을 정의하는 Pushwoosh 세그먼트 또는 목록을 선택합니다. 예를 들어, **`webinar_registered` 태그가 `true`로 설정된 사용자** 세그먼트입니다. 해당 사용자만 Journey를 통해 이동하여 **오디언스 동기화**에 도달합니다.

3. **오디언스 동기화** 지점을 추가합니다.

4. **사용자 정보를 Meta 오디언스에 동기화하는 방법** 아래에서 한 가지 옵션을 선택합니다:
   * **오디언스에 사용자 추가**. 이 단계에 도달하는 각 사용자를 선택한 Meta 오디언스에 추가합니다. 예를 들어, 가입했지만 아직 참석하지 않은 사용자에게 광고를 표시하기 시작할 때 사용합니다.
   * **오디언스에서 사용자 제거**. 이 단계에 도달하는 각 사용자를 해당 Meta 오디언스에서 제거합니다. 이 예에서는 이미 등록한 사용자에게 웨비나 광고 표시를 중단하려면 이 옵션을 선택합니다.

5. **Meta Ads 계정**에서 연결된 광고 계정을 선택합니다.

6. **오디언스**에서 Meta 오디언스(예: **웨비나**)를 선택합니다.

<img src="/integrations-meta-ads-integration-10.webp" alt="오디언스 드롭다운과 선택된 Meta 맞춤 타겟이 있는 오디언스 동기화 패널" />

7. **Apply**를 클릭하여 지점을 저장하거나 **Cancel**을 클릭하여 저장하지 않고 닫습니다.

8. Journey 구성을 완료한 후 실행합니다.

<img src="/integrations-meta-ads-integration-9.webp" alt="단계 이름, 사용자 추가 또는 제거, Meta Ads 계정, 오디언스, 적용 및 취소가 있는 오디언스 동기화 패널" />

해당 사용자가 **오디언스 동기화**에 도달하면 Meta의 **웨비나** 오디언스에서 제거되므로 더 이상 웨비나 광고가 표시되지 않습니다.

## 동작 및 오류 처리

Journey 처리는 Meta 계정 및 오디언스 가용성에 따라 달라집니다:

* Meta는 Pushwoosh가 제공하는 데이터로 사용자를 매칭할 수 있을 때만 오디언스를 업데이트합니다. Meta가 사용자를 매칭할 수 없는 경우, 해당 사용자에 대한 오디언스는 변경되지 않으며 Journey를 계속 진행합니다.
* 연결된 광고 계정이 연결 해제된 상태에서 프로필이 **오디언스 동기화** 지점에 도달하면 해당 프로필에 대한 Journey가 중지되고 Pushwoosh는 시스템 및 이메일 알림을 보냅니다.
* 선택한 오디언스가 Meta에서 발견되지 않고 API가 오류를 반환하면 해당 프로필에 대한 Journey가 중지되고 Pushwoosh는 시스템 및 이메일 알림을 보냅니다.

## 오디언스 동기화 통계
실행 후 **오디언스 동기화** 단계의 통계를 열어 진입량, 추가 및 제거, 건너뛴 프로필을 확인하세요. 지표 세부 정보는 **고객 여정 통계**의 [**오디언스 동기화**](/ko/product/statistics-and-analytics/journey-statistics/journey-element-statistics/#audience-sync)를 참조하세요.

<img src="/integrations-meta-ads-integration-11.webp" alt="총 진입, Meta 오디언스에 추가됨, Meta 오디언스에서 제거됨, 동기화되지 않고 다음 단계로 이동 건너뜀, 사용자 내보내기 및 동기화를 위한 Meta Ads 계정이 있는 오디언스 동기화 통계" />