Piano Analytics integration

Developer assistance needed

You’ll need help from your development team to set up the integration. Please share this guide with them.

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

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
Piano Visitor ID tag	visitor ID (idclient)
PostEvent.EventName	event name
PostEvent.UserID	pushwooshid (sent as pushwooshID, Piano lowercases property keys)
PostEvent.RichMediaID	src_medium
PostEvent.CampaignID	src_campaign
PostEvent.PlatformID	rendering_platform (iOS App, android, web, or pwa for any other platform)
Browser Type tag	device_type (Mobile Phone or Desktop)
Country tag	geo_country (full country name)
OS Version, Device Model, and Browser Type tags	User-Agent and Client Hints request headers

Synchronized entities

Source

• Events
• Push Stats (as the PW_NotificationSend and PW_NotificationOpen events)
• Tags (as event properties and request headers)

Destination

• Segments

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.

How does the integration work?

Flow Overview

1. Setup: Configure integration settings in both Pushwoosh and Piano Analytics accounts.
2. Event Selection: Choose which Pushwoosh system events are sent to Piano. Events keep their names in Piano.
3. Data Transfer: Pushwoosh sends the selected 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.
   • Event properties are mapped as shown in the glossary.
2. Push stats:
   • Push sends and opens reach Piano as the system events PW_NotificationSend and PW_NotificationOpen if you select them.
   • Delivery status is not sent.
3. Piano VisitorID Integration:
   • Pushwoosh sends events only for users whose device has the Piano Visitor ID tag. Set it as described in Mapping Piano VisitorID to Pushwoosh UserID/HWID.

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, fill in the following settings:

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.

Caution

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.

4. Events

In Events, select at least one event to send to Piano. Only these Pushwoosh system events are available: PW_DeviceRegistered, PW_DeviceUnregistered, PW_ApplicationOpen, PW_ApplicationMinimized, PW_ScreenOpen, PW_SiteOpened, PW_InAppPurchase, PW_NotificationSend, PW_NotificationOpen, and PW_EmailLinkClicked.

5. Unique events (optional)

Turn on Unique events enabled, set Timeframe in hours (from 1 to 168), and select events in Unique Events. For each user, Pushwoosh then also sends a <event>_unique event, for example PW_SiteOpened_unique, at most once within the timeframe.

The timeframe is shared by all unique events of a user. For example, if both PW_ApplicationOpen and PW_SiteOpened are unique and the timeframe is 24 hours, a user who opens the app and then the site on the same day gets only PW_ApplicationOpen_unique.

Creating Piano events to match Pushwoosh events

To track events sent from Pushwoosh in Piano, you need to create corresponding events manually within Piano. If you use unique events, also create a <event>_unique event for each of them, for example PW_SiteOpened_unique.

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.

4. In the Type field, select On-site.
5. In the Categories field, select Events.
6. 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

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 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 as <segment key> (Piano Autogenerated).

Import is a one-time snapshot of users who matched the segment in Piano from the same date of the previous month up to today. Pushwoosh adds the segment key to the Piano Segments list tag of matched devices. Only users whose events carry pushwooshid are matched.

Users who leave the segment in Piano later keep the tag. Importing the segment again adds the key to newly matched devices and does not remove it from devices tagged earlier.

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

If a client wants to accumulate analytics from both the Pushwoosh SDK and the Piano Analytics SDK, Pushwoosh needs to map Piano VisitorID to 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 Visitor ID within the Piano SDK using the getVisitorId 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 Visitor ID) 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. If the tag is empty, Pushwoosh does not send the user’s events to Piano.

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:

• Import Piano’s segment.
• You should see a new segment (filter) with a name constructed like segment_key (Piano Autogenerated).
• 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?

Solution: 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?

Solution: 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?

Solution: 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?

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