How to migrate from Mixpanel to Pieowl

Moving analytics tools sounds painful, but Mixpanel and Pieowl track data in a similar way. Both use events with properties and user profiles, so most code moves over with small changes. Pieowl can also pull your Mixpanel history straight from Mixpanel's API.

The plan: install Pieowl, map your tracking calls, import your history, run both tools side by side, then remove Mixpanel. Code changes usually take an hour or two. Plan another week or two of parallel tracking to check the numbers.

Prerequisites

• An existing Mixpanel setup
• A Pieowl account (start a 14-day free trial)
• Admin access to your Mixpanel project, so you can create a service account
• Access to your app's code

Get your Mixpanel credentials

You don't need to download an export file. The Pieowl importer reads your data from Mixpanel's API. It needs three things from Mixpanel:

• A service account username, which looks like name.1a2b3c.mp-service-account (example)
• The service account's secret
• Your Mixpanel project ID

Create the service account in the Service Accounts tab of your Mixpanel organization or project settings. You need Owner or Admin rights in Mixpanel, and the account needs access to the project you want to move. Also note which data center your Mixpanel project uses: US, EU or India. You'll pick it in the import form.

Install the Pieowl SDK

Install Pieowl next to Mixpanel. You'll remove Mixpanel later, once the data checks out.

For web apps, install the web SDK. It tracks page views and outgoing links for you.

npm install @pieowl/web

For Node.js and other servers, use the core SDK. It needs a client secret and is meant for trusted environments.

npm install @pieowl/sdk

There is also a package for React Native. In Next.js, Astro, Nuxt and other frameworks, you can add the script tag to your layout instead of a package. With the web SDK, create one shared instance:

import { Pieowl } from '@pieowl/web';

export const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
});

Map your events

The two APIs look alike. Here's how basic event tracking moves over. In Mixpanel, you might track a button click like this:

mixpanel.track('Button Clicked', {
  'Button Name': 'Sign Up',
  'Button Location': 'Hero'
});

In Pieowl:

pieowl.track('Button Clicked', {
  'Button Name': 'Sign Up',
  'Button Location': 'Hero'
});

The importer keeps your Mixpanel event and property names as they are. If you keep the same names in your new code, your imported history and your new data line up in the same reports. You can switch to a new naming style later, but then old and new events show up under different names.

User identification works a bit differently. Mixpanel splits it into identify and people.set:

mixpanel.identify('user_123');
mixpanel.people.set({
  '$email': 'user@example.com',
  '$first_name': 'John',
  '$last_name': 'Doe',
  'Plan': 'Premium'
});

Pieowl does both in one identify call, with built-in fields for the common ones:

pieowl.identify({
  profileId: 'user_123',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  properties: {
    Plan: 'Premium'
  }
});

For super properties, Mixpanel uses register. Pieowl calls it setGlobalProperties:

pieowl.setGlobalProperties({
  app_version: '1.0.0',
  environment: 'production'
});

mixpanel.people.increment becomes increment:

pieowl.increment({
  profileId: user.id,
  property: 'login_count',
  value: 1
});

And mixpanel.reset() on logout becomes pieowl.clear().

Import historical data

Pieowl has a built-in Mixpanel importer. In the Pieowl dashboard, open your site, go to Settings → Imports and choose Mixpanel. Fill in the form:

• Service Account and Service Secret: from the step above
• Project ID: your Mixpanel project ID
• Date Range: the period you want to bring over
• Data Residency: US, EU or India, to match your Mixpanel project
• Screen View Property (optional): for app events without a URL, the property that holds the screen name

Then start the import. Here is what it does:

• Events. It pulls your events from Mixpanel's export API one day at a time. Mixpanel's page views ($mp_web_page_view) become Pieowl screen_view events. Other event names and your own properties are kept. Mixpanel's internal properties are removed.
• Users. Each event is linked to a profile using Mixpanel's $user_id, or else its distinct_id.
• Profiles. It also pulls your user profiles from Mixpanel. $email, $first_name, $last_name and $avatar go to the built-in profile fields. Your custom profile properties are kept.
• Sessions. Mixpanel doesn't store sessions, so Pieowl builds them from the imported events after the import.

The importer stays within Mixpanel's API rate limits, so a long date range can take several hours. You can watch its progress on the Imports page.

Run in parallel

Before you remove Mixpanel, run both tools for one to two weeks. That lets you check that event counts match and that users are identified correctly.

A small wrapper sends each event to both tools:

function trackEvent(eventName, properties) {
  if (typeof mixpanel !== 'undefined') {
    mixpanel.track(eventName, properties);
  }

  pieowl.track(eventName, properties);
}

trackEvent('Button Clicked', { 'Button Name': 'Sign Up' });

After a week, compare daily event counts in both tools. Expect them to be close, not exact, because each tool filters bots and counts sessions in its own way. Check that user profiles look right. Rebuild a key funnel in Pieowl and compare its conversion rates with Mixpanel.

Remove Mixpanel

Once the data matches, remove the Mixpanel SDK. For npm packages, uninstall it:

npm uninstall mixpanel-browser

Then search your code for any mixpanel.* calls left and replace them with the Pieowl versions. If you used the wrapper from the parallel step, remove the Mixpanel line or call Pieowl directly.

pieowl.track('Button Clicked', { 'Button Name': 'Sign Up' });

Don't forget to remove any Mixpanel script tags if you loaded their SDK from a CDN.

Verify your setup

After you remove Mixpanel, watch Pieowl for a few days. Check that events keep flowing in the realtime view, that user profiles have the right properties, and that your funnels and reports still work.

No events? Make sure you use the right Client ID and that Pieowl is set up before any tracking call. In the browser's Network tab, you should see requests to api.pieowl.com.

Next steps

The SDK documentation covers more, such as server-side tracking and framework setups.

For framework setup, see these guides:

• Next.js analytics guide for Next.js apps
• React analytics guide for React apps
• Express analytics guide for Express apps
• Python analytics guide for Python apps, using the HTTP API