# Piano Analytics 통합

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

[Piano Analytics](https://piano.io/product/analytics/)는 기업이 사람들이 웹사이트 및 앱과 상호 작용하는 방식을 이해하는 데 도움을 주는 도구입니다. 사용자 행동에 대한 데이터를 수집하고 보고서 및 시각화를 통해 인사이트를 제공합니다. 이 정보는 기업이 디지털 제품과 마케팅 활동을 개선하는 방법에 대해 더 나은 결정을 내리는 데 도움이 됩니다.

[Piano Analytics](https://piano.io/product/analytics/)와 Pushwoosh를 통합하면 상세한 사용자 행동 인사이트를 통해 정밀한 세그먼트를 생성하고, 적절한 사용자에게 적시에 고도로 타겟팅된 푸시 알림, 이메일, 인앱 메시지를 보낼 수 있습니다.

## 통합 개요

### 통합 유형

*   **Destination**: 데이터가 Piano Analytics에서 Pushwoosh로 전송됩니다.
*   **Source**: 데이터가 Pushwoosh에서 Piano Analytics로 전송됩니다.

### 전제 조건

Pushwoosh와 Piano Analytics의 유료 계정

### 용어집 (엔티티 이름이 다른 경우 매핑)

Pushwoosh와 Piano Analytics를 통합할 때 특정 엔티티 이름은 두 플랫폼 간에 다를 수 있습니다. 다음은 Pushwoosh와 Piano Analytics 간의 매핑입니다:

| Pushwoosh | Piano Analytics |
| --- | --- |
| UserID/hwid | visitorID |
| PostEvent.EventName | PianoEvent.Name |
| PostEvent.UserID | PianoEvent.PushwooshID |
| PostEvent.CampaignID | PianoEvent.SrcMedium |
| PostEvent.PlatformID | PianoEvent.DeviceType |

### 동기화된 엔티티

**Source**

*   Events
*   Push Stats
*   Tags (이벤트 속성으로)

**Destination**

*   Segments

### 사용 사례

**통합 분석**

Pushwoosh 참여 데이터를 Piano Analytics와 결합하여 포괄적인 사용자 인사이트를 얻으세요. 이를 통해 여러 터치포인트에서 사용자 행동 및 상호 작용에 대한 전체적인 뷰를 얻을 수 있습니다.

**세분화**

Piano Analytics 데이터를 기반으로 Pushwoosh에서 타겟 사용자 세그먼트를 생성하세요. 이 향상된 세분화를 사용하여 개인화되고 효과적인 마케팅 캠페인을 제공하세요.

**성과 모니터링**

플랫폼 전반에 걸쳐 캠페인 효과와 사용자 상호 작용을 추적하세요.

### 통합은 어떻게 작동하나요?

##### 흐름 개요

1.  **설정**: Pushwoosh와 Piano Analytics 계정 모두에서 통합 설정을 구성합니다.
2.  **이벤트 매핑**: Pushwoosh 이벤트를 Piano 이벤트에 매핑합니다(예: PostEvent.EventName을 PianoEvent.Name에).
3.  **데이터 전송**: Pushwoosh는 이벤트(Post Events 및 Tracking Log Events)를 Piano Analytics로 보냅니다.
4.  **세그먼트 가져오기**: Piano Analytics는 잠재고객 세분화를 위해 세그먼트 데이터를 Pushwoosh로 보냅니다.

##### 기술적 흐름

1.  **Post Events**
    *   Pushwoosh는 이벤트 데이터를 Piano Analytics로 보냅니다.
    *   속성은 다음과 같이 매핑됩니다:
        *   UserID (Pushwoosh) > PushwooshID (Piano)
        *   CampaignID (Pushwoosh) > SrcMedium (Piano)
        *   PlatformID (Pushwoosh) > DeviceType (Piano)
2.  **Tracking Log Events**:
    *   Pushwoosh는 추적 데이터(예: Push Sent, Push Delivered)를 Piano Analytics로 보냅니다.
    *   이 데이터는 전달 및 참여 지표로 Piano Analytics를 풍부하게 합니다.
3.  **Piano VisitorID 통합**:
    *   선택적으로, SDK 전반에 걸친 통합 분석을 위해 Piano VisitorID를 Pushwoosh와 통합할 수 있습니다.

## 통합 설정하기

통합을 설정하려면 Pushwoosh 계정에서 **설정 > 타사 통합**으로 이동하여 **Piano**를 찾으세요. **구성**을 클릭합니다.

<img src="/integrations-piano-analytics-integration-1.webp" alt="Pushwoosh의 Piano 통합 설정"/>

열리는 창에서 다음 자격 증명을 제공하세요:

1.  사이트 ID

사이트 ID를 찾으려면 Piano 계정에 로그인하여 **분석 > 데이터 수집 포털 > 대시보드**로 이동하세요. 관련 웹사이트를 찾아 ID를 복사합니다.

<img src="/integrations-piano-analytics-integration-2.webp" alt="Piano Analytics에서 사이트 ID 찾기"/>

2.  수집 도메인

수집 도메인을 찾으려면 **태깅 > 수집 도메인**으로 이동하세요. 수집 도메인 ID를 복사합니다. 수집 도메인을 **https:// 접두사 없이** **\*\*\*\*.pa-cd.com** 형식으로 입력해야 합니다.

<img src="/integrations-piano-analytics-integration-3.webp" alt="Piano의 수집 도메인 설정"/>

3.  Piano API 액세스 및 시크릿 키

키를 얻으려면:

*   Piano 계정에서 계정 이름 아래의 **프로필 보기**를 클릭합니다.

<img src="/integrations-piano-analytics-integration-4.webp" alt="Piano의 계정 프로필 메뉴"/>

*   **API 키** 탭으로 이동하여 명확한 이름과 설명으로 새 키를 만듭니다. 그런 다음 **확인**을 클릭합니다.

<img src="/integrations-piano-analytics-integration-5.webp" alt="Piano 계정에서 API 키 생성하기"/>

*   열리는 창에서 **액세스 키**와 **시크릿 키**를 복사합니다.

<Aside type="caution">
보안상의 이유로 **시크릿 키**는 한 번만 표시됩니다. 계속하기 전에 두 키를 모두 안전한 곳에 저장했는지 확인하세요.
</Aside>

<img src="/integrations-piano-analytics-integration-6.webp" alt="Piano 계정에서 API 키 복사하기"/>

*   Pushwoosh의 **API 키** 필드에 **액세스 키**와 **시크릿 키**를 밑줄로 구분하여 모두 입력합니다. 예: **accesskey_secretkey**.

<img src="/integrations-piano-analytics-integration-7.webp" alt="Pushwoosh 통합에 API 키 입력하기"/>

### Pushwoosh 이벤트와 일치하는 Piano 이벤트 생성하기

Pushwoosh에서 보낸 이벤트를 Piano에서 추적하려면 Piano 내에서 해당 이벤트를 수동으로 생성해야 합니다.

Piano 계정에서 하는 방법은 다음과 같습니다:

1.  **설정 > 데이터 관리 > 데이터 모델**로 이동합니다.
2.  **이벤트**를 선택하고 더하기 아이콘을 클릭하여 새 이벤트를 만듭니다.
3.  열리는 창에서 이벤트 이름과 설명을 제공합니다(예: _**"pw\_siteopened"**_).

<Aside type="note">
이벤트 이름은 대소문자를 구분하지 않습니다. 예를 들어 Pushwoosh에서 이벤트에 대문자 이름(_PW_SiteOpened_)을 생성하면 Piano의 _pw_siteopened_ 이벤트와 일치합니다.
</Aside>

4.  **유형** 필드에서 **On-site**를 선택합니다.
5.  **카테고리** 필드에서 **이벤트**를 선택합니다.
6.  **저장**을 클릭합니다.

<img src="/integrations-piano-analytics-integration-8.webp" alt=""/>

### Piano에서 웹사이트 시간대 설정하기

Piano에서 웹사이트에 대한 올바른 시간대를 설정하는 것은 정확한 데이터 추적 및 분석에 매우 중요합니다. 가장 좋은 방법은 이벤트를 보내고 분석을 수행하는 위치와 시간대를 일치시키는 것입니다. 이렇게 하면 시간 불일치가 제거됩니다.

Piano에서 시간대를 편집하려면 **대시보드**로 이동하여 사이트 정보가 포함된 줄을 클릭합니다. 팝업 창에서 **편집**을 클릭하고 원하는 시간대를 선택합니다. 그런 다음 **저장**을 클릭합니다.

<img src="/integrations-piano-analytics-integration-9.webp" alt="Piano에서 웹사이트 시간대 설정하기"/>

### Piano에서 Pushwoosh로부터 전송된 이벤트를 식별하기 위한 속성 생성

데이터 관리를 더 쉽게 하려면 Piano에서 Pushwoosh 이벤트와 연결할 수 있는 속성을 만드세요. 이렇게 하면 Pushwoosh에서 보낸 이벤트를 쉽게 식별할 수 있습니다.

속성을 만드는 방법은 다음과 같습니다:

1.  Piano에서 **설정 > 데이터 관리 > 속성**으로 이동합니다.
2.  **속성 생성**을 클릭합니다.
3.  **이름** 필드에 **pushwooshid**를 입력합니다.
4.  **속성 키** 필드에 **pushwooshid**를 입력합니다.
5.  **유형**을 **문자열**로 설정합니다.
6.  **저장**을 클릭합니다.

<img src="/integrations-piano-analytics-integration-10.webp" alt="Piano에서 Pushwoosh 이벤트를 위한 속성 생성하기"/>

### Pushwoosh 이벤트가 Piano로 전송되는지 확인하기

Pushwoosh에서 설정한 이벤트가 Piano로 성공적으로 전송되는지 확인하려면 다음 단계를 따르세요:

1.  Piano 계정에서 **탐색기 > 잠재고객 > 전체 트래픽**으로 이동합니다.
2.  **pushwooshid** 속성이 비어 있지 않은 이벤트를 기반으로 세그먼트를 만듭니다.

<img src="/integrations-piano-analytics-integration-11.webp" alt="Piano에서 이벤트를 기반으로 세그먼트 생성하기"/>

필터링된 뷰에는 관련 이벤트를 포함한 전체 트래픽 정보가 표시됩니다.

<img src="/integrations-piano-analytics-integration-12.webp" alt="Pushwoosh 이벤트가 포함된 전체 트래픽 뷰"/>

Pushwoosh에서 보낸 이벤트에 대한 더 세분화된 뷰를 보려면 **콘텐츠 > 이벤트**로 이동하세요. 이 섹션에서는 각 이벤트가 발생한 횟수를 포함하여 Pushwoosh에서 보낸 모든 이벤트에 대한 자세한 분석을 제공합니다.

<img src="/integrations-piano-analytics-integration-13.webp" alt="Pushwoosh의 이벤트 상세 분석"/>

### Piano에서 세그먼트 생성하기

통합 설정을 완료하면 Piano 내에서 Pushwoosh에서 보낸 이벤트를 분석할 수 있습니다. 이러한 이벤트에 액세스하려면 Piano 계정에서 **탐색기 > 콘텐츠 > 이벤트**로 이동하세요.

<img src="/integrations-piano-analytics-integration-14.webp" alt="Piano Analytics의 이벤트 뷰"/>

그런 다음 이러한 이벤트를 사용하여 [세그먼트를 생성](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment)하세요. 세그먼트를 생성할 때 이벤트를 필터링하기 위해 이전에 생성한 **`pushwooshid`** 속성을 선택합니다.

<img src="/integrations-piano-analytics-integration-15.webp" alt="pushwooshid 속성으로 세그먼트 생성하기"/>

세그먼트에 명확하고 설명적인 이름을 지정해야 합니다. 저장된 세그먼트의 고유 식별자인 **세그먼트 키**는 나중에 Pushwoosh로 세그먼트를 보낼 때 필요합니다.

<img src="/integrations-piano-analytics-integration-16.webp" alt="Piano에서 세그먼트 이름 지정하기"/>

### Piano에서 Pushwoosh로 세그먼트 보내기

<Aside type="note">
계정 소유자만 세그먼트를 가져올 수 있습니다.
</Aside>

Pushwoosh가 Piano에서 세그먼트를 검색할 수 있도록 하려면 생성한 SegmentKey를 Pushwoosh에 제공해야 합니다. 세그먼트의 SegmentKey를 찾으려면 **분석 > 라이브러리 > 세그먼트**로 이동하세요. 필요한 세그먼트를 클릭하고 **세그먼트 키**를 복사합니다.

<img src="/integrations-piano-analytics-integration-17.webp" alt="Piano에서 Pushwoosh로 보낼 세그먼트 선택하기"/>

Pushwoosh 통합 섹션에서 **Piano**를 찾아 **세그먼트 가져오기**를 클릭합니다. 그런 다음 복사한 세그먼트 키를 입력합니다.

<img src="/integrations-piano-analytics-integration-18.webp" alt="통합을 통해 Piano에서 Pushwoosh로 세그먼트 가져오기"/>

가져오기가 성공하면 확인 메시지가 표시됩니다.

<img src="/integrations-piano-analytics-integration-19.webp" alt="Piano에서 Pushwoosh로 세그먼트 가져옴"/>

가져온 세그먼트는 Pushwoosh에서 액세스할 수 있습니다. 가져오기가 완료되면 Pushwoosh 계정의 **잠재고객 > 세그먼트** 섹션에 나열됩니다.

<img src="/integrations-piano-analytics-integration-20.webp" alt="Pushwoosh에 있는 Piano에서 가져온 세그먼트"/>

## SDK 전반에 걸친 누적 분석을 위해 Piano VisitorID를 Pushwoosh UserID/HWID에 매핑하기

클라이언트가 Pushwoosh SDK와 Piano Analytics SDK 모두에서 분석을 누적하려는 경우, Pushwoosh는 Piano VisitorID를 Pushwoosh UserID/HWID에 매핑해야 합니다. 해결책은 사용자/기기에 대해 Piano VisitorID 태그를 Pushwoosh로 보내는 것입니다.

이를 위해 다음을 수행하세요:

1.  애플리케이션을 위해 Pushwoosh 측에 '**Piano Visitor ID**'라는 태그를 만듭니다. 참고: 태그 이름은 설명된 것과 정확히 같아야 합니다.
2.  클라이언트의 애플리케이션 측에서 Piano SDK 내에서 **getVisitorId** 메서드를 사용하여 Piano Visitor ID를 가져옵니다.
3.  클라이언트의 애플리케이션 측에서 Pushwoosh SDK를 사용하여 태그 값으로 `setTags` 요청을 한 번 호출합니다.

사용자/기기에 태그 값(Piano Visitor ID)이 있는 경우, Pushwoosh는 이를 자동으로 클라이언트 ID로 Piano Analytics에 대한 요청에 포함합니다. Piano Analytics 측에서는 고유한 방문자 ID 값으로 변환됩니다.

## 코드 예제

##### Web Push SDK (JavaScript)

```javascript
Pushwoosh.push(function(api) {
// Set tags for a user
api.setTags({
'Piano Visitor ID': pa.getVisitorID(),
});
```

##### Android (Java)

```java
String value1 = PianoAnalytics.getInstance().visitorId();
TagsBundle pianoTag = new TagsBundle.Builder()
    .putString("Piano Visitor ID", value1)
    .build();
Pushwoosh.getInstance().setTags(pianoTag);
```

##### iOS (Swift)

```swift
var pianoId: String = pa.getVisitorId(completionHandler: { visitorId in
Pushwoosh.sharedInstance().setTags([
 "Piano Visitor ID": visitorId
 ])
})
```

##### iOS (Objective-C)

```objective-c
__block NSString *pianoId;
[pa getVisitorIdWithCompletionHandler:^(NSString *visitorId) {
    Piano Visitor ID = visitorId;
    [[Pushwoosh sharedInstance] setTags:@{@"Piano Visitor ID": visitorId}];
}];
```

일반적으로 Pushwoosh는 각 요청 내에서 장치 및 기타 정보를 Piano Analytics에 제공하기 위해 장치 태그를 사용합니다. 다음은 사용되는 일반적인 태그 목록입니다:

*   **국가**
*   **장치 모델**
*   **OS 버전**
*   **브라우저 유형** (경우에 따라)

## 통합이 작동하는지 확인하는 방법

#### Source: Piano Analytics로 전송된 이벤트 감지

Piano Analytics로 전송된 이벤트를 감지하는 두 가지 쉬운 방법이 있습니다:

##### 스트림 검사기

1.  **Piano Analytics** 계정으로 이동합니다.
2.  **설정** > **데이터 수집 포털** > **도구** > **스트림 검사기**로 이동합니다.
3.  확인하려는 연결된 사이트를 선택합니다.
4.  검사할 이벤트를 선택하고 세션을 시작합니다.
5.  이벤트가 Piano Analytics에 의해 수신되었는지 확인합니다.

##### 전체 트래픽에서 이벤트 확인

1.  **Piano Analytics** 계정으로 이동합니다.
2.  **설정** > **탐색기** > **잠재고객** > **전체 트래픽**으로 이동합니다.
3.  아래 메뉴에서 사이트와 날짜 범위를 선택합니다.

#### Destination: Piano의 세그먼트 가져오기

대상 측에서 통합을 확인하려면:

*   Piano의 세그먼트를 가져옵니다.
*   `segment_key (Piano Autogenerated)`와 같이 구성된 이름의 새 세그먼트(필터)가 표시되어야 합니다.
*   현재 장치 처리에 대한 최신 정보를 얻으려면 세그먼트를 다시 계산합니다.

## FAQ 문제 해결: 일반적인 문제

#### Pushwoosh에서 Piano Analytics로 이벤트가 올바르게 전송되도록 하려면 어떻게 해야 하나요?

**해결책**: Piano의 스트림 검사기를 사용하거나 Piano Analytics의 전체 트래픽을 확인하여 Pushwoosh에서 들어오는 이벤트를 모니터링하세요.

#### 세그먼트 데이터가 Pushwoosh로 올바르게 가져오지 않으면 어떻게 해야 하나요?

**해결책**: Piano의 세그먼트 키가 Pushwoosh의 설정과 일치하는지 확인하세요. 세그먼트 크기 계산이나 데이터 검색에 오류가 있는지 확인하세요.

#### 향상된 분석을 위해 Piano VisitorID를 Pushwoosh와 통합할 수 있나요?

**해결책**: 예, Pushwoosh에서 특정 태그를 설정하고 Piano의 SDK를 사용하여 VisitorID를 가져오면 플랫폼 간에 사용자 ID를 동기화할 수 있습니다.

#### API 키 구성에 문제가 있으면 어떻게 해야 하나요?

**해결책**: API 요청 로그를 검토하고, 올바른 엔드포인트 URL과 인증 토큰(API 키)을 확인하고, 두 서비스 중 하나에서 보고된 서버 측 오류가 있는지 확인하세요.