Importing Campaign Data using the Management API

This guide describes how to import campaign metadata such as source, medium, content, referral path, and other custom campaign data.

Introduction

Importing campaign data into Google Analytics enables a more customized analysis of campaign performance. It allows you to include data such as new campaign classifications and variations, in addition to the standard Google Analytics campaign tracking parameters.

It also simplifies and reduces the amount of campaign data you need to send in the tracking code. A single campaign ID sent to Google Analytics at collection time can be joined with your imported campaign data to populate campaign and custom dimensions and metrics in your reports.

This article discusses the following Google Analytics technologies:

  • Custom campaigns
  • Data import
  • Web tracking plugins

To learn more about these technologies, see the related resources.

Overview

To import campaign data into Google Analytics:

  1. Set campaign information
  2. Configure your account
  3. Analyse and take action

Set campaign information

Setting campaign information for a user is required in order to allow imported campaign data to be available for analysis. You can do this by setting the campaign code/Id which will be used to join your imported data.

Use one of these three ways to set campaign data for your users:

  1. Tag your campaign URLs using Google Analytics campaign tracking parameters.
  2. Set the campaign data directly.
  3. If you tag URLs using non-Google Analytics campaign tracking parameters, you can use an analytics.js plugin to map your campaign values to those recognized by Google Analytics.

Option 1: Tag your campaign URLs

Tag campaign destination URLs with the utm_id parameter. Google Analytics will then associate this campaign ID with users who follow this URL. For example:

http://www.example.com?utm_id=1234

Option 2: Set campaign data directly

If you have a custom implementation and campaign information is available then it can be set directly on the tracker and associated with the user. For example:

analytics.js

// Create the tracker.
ga('create', 'UA-XXXX-Y', 'auto');

// Set the campaign code/id directly.
ga('set', 'campaignId', '1234');

// Send the page view.
ga('send', 'pageview');
See the analytics.js developer guide for details.

gtag.js

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments)};
  gtag('js', new Date());

// Set the campaign code/id directly.
  gtag('set', 'campaign_id', '1234');

  gtag('config', 'TAG_ID');
</script>
See the gtag.js developer guide for details.

Android SDK v4

// The campaign code/id is sent with this hit.
tracker.send(new HitBuilders.ScreenViewBuilder()
    .set(Fields.CAMPAIGN_ID, '1234')
    .build()
);
See the Android SDK v4 - Campaign Measurement developer guide for details.

iOS SDK v3

// Get the tracker.
id tracker = [[GAI sharedInstance] trackerWithName:@"tracker"
                                                    trackingId:@"UA-XXXX-Y"];

// Create a GAIDictionaryBuilder to hold the hit parameters.
GAIDictionaryBuilder *hitParams = [[GAIDictionaryBuilder alloc] init];

// Set campaign code/id directly on the dictionary.
[hitParams set:kGAICampaignId value:@"1234"];

// The campaign id/code is sent with this hit.
[tracker send:[[[GAIDictionaryBuilder createAppView] setAll:hitParams] build]];
See the iOS SDK - Campaign Measurement developer guide for details.

Measurement protocol

v=1             // Version.
&tid=UA-XXXX-Y  // Tracking ID / Property ID.
&cid=555        // Anonymous Client ID.

&t=pageview     // Pageview hit type.
&dh=mydemo.com  // Document hostname.
&dp=/home       // Page.
&dt=homepage    // Title.
&ci=1234        // Campaign code/id.
See the Measurement Protocol developer guide for details.

Option 3 (analytics.js): Plugin with custom campaign tracking

If you are not using the utm_id in your URLs to track your campaign Id, you can follow the example in the Plugins - Web Tracking (analytics.js) developer guide which shows how to capture custom campaign values from a page's URL and set them on the tracker.

Configure your account

There are a few one time operations that you will need to make in the Google Analytics Admin section. The Google Analytics administration steps are:

  1. Create custom dimensions
  2. Create a data set
  3. Prepare and upload data

Create custom dimensions

In addition to the standard campaign dimensions available in Google Analytics you can define new session scoped custom dimensions to import custom campaign data. For example, you could create a custom dimension called Campaign Group. From the Admin page the steps to create a custom dimension are:

  1. Click Custom Definitions -> Custom Dimensions -> + New Custom Dimension.
  2. Name the dimensions and set the scope to Session.
  3. Click Create.
Figure 1: Custom campaign dimension list.

Create a data set

To import your campaign data you must create a data set. A data set can only be created through the Web Interface.

Under the property tab of the admin page perform the following steps:

  1. Select Data Import.
  2. Click New Data Set.
  3. Select Campaign Data for the type and click Next Step.
  4. Name the data set and select at least one view (profile) and click Next Step.
  5. For the Key select Campaign Code.
  6. For Imported Data select the dimensions for the data you intend to import.
  7. Select an Overwrite hit data option.
  8. Click Save.
Figure 2: Creating a data set.

Prepare campaign data for upload

Google Analytics expects campaign data to be uploaded in a properly formatted comma separated file (CSV). You need to make sure the campaign data meets these requirements before uploading.

The primary modifications and validations that you need to make to the CSV file are:

  • Rename the column headers to those recognized by Google Analytics. You can retrieve the header from the data set details page in the web interface.
  • Add any required values that are missing.

For example you may have the campaign data in the following format:

Figure 3: Exported campaign data.

Once you have prepared the CSV file, the format should look similar to the following example:

ga:campaignCode,ga:medium,ga:source,ga:dimension1
1234,email,Newsletter,Spring
1235,email,Newsletter,Summer
1236,email,Newsletter,Fall

Upload campaign data

Once you've created your session scoped custom dimensions and data set, and prepared your campaign data for upload in a CSV file, you're ready to upload your campaign data using the Management API or through the web interface.

After the campaign data has been uploaded, validated, and processed, Campaign Ids will be joined with the uploaded campaign data when a match occurs on incoming hits sent to Google Analytics from your property.

Analyze and take action

With the component pieces in place it is now possible to analyze your campaign performance and take action. The existing acquisition reports can be used to analyze the standard campaign parameters or apply a segment using your imported custom dimensions (or add your custom dimensions as a secondary dimension). It is also possible to create your own custom report or automate your analysis by composing your own query using the Core Reporting API.

Create a custom report

To get a much more customized view of campaign performance you can create a custom report. For example it is possible create a customized campaign report from the reporting page as follows:

  1. In the left hand navigation click Acquisition -> Campaigns.
  2. Change the report type to be Flat Table.
  3. Click Customize at the top of the report.
  4. In the dimension drill down add the Campaign Group custom dimension created above.
  5. Click Save.

Related resources

To learn more about each of the features: