Piano Analytics integration

Piano Analytics is a tool that helps businesses understand how people interact with their websites and apps. It collects data about user behavior and provides insights through reports and visualizations. This information helps businesses make better decisions about how to improve their digital products and marketing efforts.

Integrating Piano Analytics and Pushwoosh allows for detailed user behavior insights to create precise segments and send highly targeted push notifications, emails, and in-app messages to the right users at the right time.

Integration overview

Integration type

• Destination: Data is sent from Piano Analytics to Pushwoosh.

• Source: Data is sent from Pushwoosh to Piano Analytics.

Prerequisites

Paid accounts in both Pushwoosh and Piano Analytics

Use cases

Unified analytics

Combine Pushwoosh engagement data with Piano Analytics for comprehensive user insights. This allows you to get a holistic view of user behavior and interactions across multiple touchpoints.

Segmentation

Create targeted user segments in Pushwoosh based on Piano Analytics data. Use this enhanced segmentation to deliver personalized and effective marketing campaigns.

Performance monitoring

Track campaign effectiveness and user interaction across platforms.

Glossary (mapping entity names if they are different)

When integrating Pushwoosh and Piano Analytics, certain entity names may vary between the two platforms. Here are the mappings between Pushwoosh and Piano Analytics:

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

Synchronized entities

Source

• Events

• Push Stats

• Tags (as event attributes)

Destination

• Segments

How does the integration work?

Flow Overview

1. Setup: Configure integration settings in both Pushwoosh and Piano Analytics accounts.

2. Event Mapping: Map Pushwoosh events to Piano events (e.g., PostEvent.EventName to PianoEvent.Name).

3. Data Transfer: Pushwoosh sends events (Post Events and Tracking Log Events) to Piano Analytics.

4. Segment Import: Piano Analytics sends segment data to Pushwoosh for audience segmentation.

Technical Flow

1. Post Events

Pushwoosh sends event data to Piano Analytics. Attributes are mapped as follows:

• UserID (Pushwoosh) -> PushwooshID (Piano)

• CampaignID (Pushwoosh) -> SrcMedium (Piano)

• PlatformID (Pushwoosh) -> DeviceType (Piano)

1. Tracking Log Events

Pushwoosh sends tracking data (e.g., Push Sent, Push Delivered) to Piano Analytics. This data enriches Piano Analytics with delivery and engagement metrics.

1. Piano VisitorID Integration

Optionally, integrate Piano VisitorID with Pushwoosh for unified analytics across SDKs.

Setting up the integration

To set up the integration, go to Settings > 3rd Party Integrations in your Pushwoosh account and locate Piano. Click Configure.

In the window that opens, provide the following credentials:

1. Site ID

To locate your Site ID, log in to your Piano account and go to Analytics > Data Collection Portal > Dashboard. Find the relevant website and copy its ID.

2. Collection Domain

To find the Collection Domain, navigate to Tagging > Collection Domains. Copy the Collection Domain ID. Make sure to enter the collection domain in the ****.pa-cd.com format without the https:// prefix.

3. Piano API Access and Secret keys

To get the keys:

• In your Piano account, click on See profile below your account name.

• Navigate to the API Keys tab and create a new key with a clear name and description. Then click OK.

• In the window that opens, copy your Access Key and the Secret Key.

For security reasons, the Secret Key will only be displayed once. Please make sure you save both keys in a safe place before continuing.

• In the API key field in Pushwoosh, enter both the Access Key and Secret Key, separated by an underscore. For example: accesskey_secretkey.

Creating Piano events to match Pushwoosh events

To track events sent from Pushwoosh in Piano, you need to create corresponding events manually within Piano.

Here's how to do it in your Piano account:

1. Go to Settings > Data management > Data model.

2. Select Events and click the plus icon to create a new event.

3. In the window that opens, provide the event name and description, for example, "pw_siteopened".

Note: The naming of events is not case-sensitive. If you create an uppercase name for an event in Pushwoosh, for example, PW_SiteOpened, it will match the pw_siteopened event in Piano.

1. In the Type field, select On-site.

2. In the Categories field, select Events.

3. Click Save.

Setting your website’s time zone in Piano

Setting the correct time zone for your website in Piano is crucial for accurate data tracking and analysis. The best practice is to match the time zone with the location where you're sending events and conducting analysis. This eliminates time discrepancies.

To edit the timezone in Piano, go to Dashboard and click the line containing your site information. In the pop-up window, click Edit and select the desired time zone. Then, click Save.

Creating a property for identifying events sent from Pushwoosh in Piano

To make data management easier, create a property in Piano that can be associated with Pushwoosh events. This will allow you to easily identify events sent from Pushwoosh.

Here's how to create the property:

1. In Piano, go to Settings > Data Management > Properties.

2. Click Create Property.

3. In the Name field, enter pushwooshid.

4. In the Property Key field, enter pushwooshid.

5. Set the Type to String.

6. Click Save.

Checking if Pushwoosh events are sent to Piano

To verify that events set up in Pushwoosh are successfully sent to Piano, follow these steps:

1. In your Piano account, go to Explorer > Audience > Overall Traffic.

2. Create a segment based on events where the property pushwooshid is not empty.

The filtered view will display overall traffic information, including any associated events.

For a more granular view of events sent from Pushwoosh, navigate to Content > Events. This section provides a detailed breakdown of all the events sent from Pushwoosh, including the number of times each event occurred.

Creating segments in Piano

Once you've completed the integration setup, you can start analyzing events sent from Pushwoosh within Piano. To access these events, navigate to Explorer > Content > Events in your Piano account.

Then create Segments using these events. When creating segments, select the `pushwooshid` property you’ve created earlier to filter events.

Make sure to give your segment a clear and descriptive name. The Segment Key, which is a unique identifier for the saved segment, will be needed later for sending segments to Pushwoosh.

Sending segments from Piano to Pushwoosh

Please note that only Account Owners can import segments.

To enable Pushwoosh to retrieve segments from Piano, provide Pushwoosh with the SegmentKey you created. To find the SegmentKey for a segment, go to Analysis > Library > Segments. Click on the segment you need and copy the Segment Key.

In the Pushwoosh Integrations section, locate Piano and click on Import Segment. Then, enter the Segment key you copied.

If the import is successful, you'll see a confirmation message.

You can access your imported segments in Pushwoosh. Once the import is complete, they'll be listed in the Audience > Segments section of your Pushwoosh account.

Mapping Piano VisitorID to Pushwoosh UserID/HWID for accumulated analytics across SDKs

If the client wants to accumulate analytics from both SDK’s on the Piano Analytics side then Pushwoosh needs to know how to map Piano VisitorID and Pushwoosh UserID/HWID. The solution is to send a Piano VisitorID tag to Pushwoosh for the user/device.

For this, do the following:

1. Create a tag named 'Piano Visitor ID' on the Pushwoosh side for the application. Note: The tag name must be exactly as described.

2. On the client’s application side: Get the Piano VisitorID within the Piano SDK using thegetVisitorId method.

3. On the client’s application side: Use the Pushwoosh SDK to call the setTags request with the tag value once.

If the tag value (Piano VisitorID) exists for the user/device, Pushwoosh will automatically include it as Client ID in requests to Piano Analytics. On the Piano Analytics side, it will be transformed into a unique visitor ID value.

Code examples

Web Push SDK (Javascript)

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

Android (Java)

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

iOS (Swift)

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

iOS (Objective-C)

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

In general, Pushwoosh uses device tags to provide device and other information to Piano Analytics within each request. Here is a list of common tags used:

• Country

• Device Model

• OS Version

• Browser Type (in some cases)

How to verify the integration is working

Source: Detecting events sent to Piano Analytics

There are two easy ways to detect events that were sent to Piano Analytics:

Stream Inspector

1. Go to your Piano Analytics account.

2. Navigate to Settings -> Data Collection Portal -> Tools -> Stream Inspector.

3. Choose the connected site you want to check.

4. Select the events you want to inspect and start a session.

5. Verify that the events were received by Piano Analytics.

Check events in Overall Traffic

1. Go to your Piano Analytics account.

2. Navigate to Settings -> Explorer -> Audience -> Overall Traffic.

3. Choose the site and date range in the menu below.

Destination: Importing Piano's segment

To verify the integration on the destination side:

1. Import Piano's segment.

2. You should see a new segment (filter) with a name constructed like segment_key (Piano Autogenerated).

3. Recalculate the segment to get up-to-date information about current devices processing.

FAQ troubleshooting: Common issues

How can I ensure events are correctly sent from Pushwoosh to Piano Analytics?

Use Piano's Stream Inspector or check Overall Traffic in Piano Analytics to monitor incoming events from Pushwoosh.

What should I do if segment data isn't imported correctly into Pushwoosh?

Ensure the Segment Key from Piano matches the setup in Pushwoosh. Check for any errors in segment size calculations or data retrieval.

Can I integrate Piano VisitorID with Pushwoosh for enhanced analytics?

Yes, by setting up a specific tag in Pushwoosh and using Piano's SDK to fetch VisitorID, you can synchronize user IDs across platforms.

What should I do if there are issues with API key configurations?

Review API request logs, ensure correct endpoint URLs and authentication tokens (API keys), and check for any server-side errors reported by either service.