​
Overview

Attribution tracking in Masivo enables you to measure and analyze the complete customer journey across all touchpoints. By implementing proper attribution parameters, you can track which marketing campaigns, channels, and touchpoints drive customer behavior, purchases, and engagement. This guide covers the complete attribution system, from generating tracking IDs to analyzing campaign performance.

Attribution data is automatically collected from deeplinks and can be manually attached to events. All attribution parameters are optional but provide valuable insights when implemented consistently across your marketing campaigns.

​
Understanding Attribution Parameters

​
Attribution Data Structure

Attribution data in Masivo consists of several key parameters that help track the customer journey:

interface AttributionData {
  tracking_id?: string; // Unique identifier for tracking user sessions
  revenue?: number; // Revenue attributed to this touchpoint
  cost?: number; // Marketing cost associated with this attribution
  utm_source?: string; // Traffic source (e.g., "google", "facebook")
  utm_medium?: string; // Marketing medium (e.g., "cpc", "email", "social")
  utm_campaign?: string; // Campaign name (e.g., "summer-sale-2024")
  utm_term?: string; // Paid search keywords
  utm_content?: string; // Ad variation or email version
  utm_referral?: string; // Specific referral source
  ad_provider?: string; // Advertising platform (e.g., "google_ads")
}

​
How Attribution Works in Masivo

Attribution data flows through the system in several ways:

  1. Automatic Collection: Generated automatically when customers click deeplinks
  2. Event Attribution: Manually attached to events via the API
  3. Journey Tracking: Automatically propagated through customer journey steps
  4. Analytics: Aggregated for campaign performance analysis

​
1. Tracking ID Generation and Usage

​
Understanding Tracking IDs

The tracking_id is a unique identifier that connects customer actions across your marketing funnel. It’s automatically generated for deeplinks and can be manually created for custom tracking scenarios.

​
Automatic Tracking ID Generation

When customers click on a Masivo deeplink, a tracking_id is automatically generated:

// This happens automatically in Masivo's deeplink handler
import { v4 as uuidv4 } from "uuid";

const tracking_id = uuidv4(); // e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Added to attribution data
const attribution = {
  tracking_id,
  utm_source: "email",
  utm_medium: "newsletter",
  utm_campaign: "spring-collection"
};

// Appended to destination URL
const destinationUrl =
  "https://yourapp.com/products?$tracking_id=f47ac10b-58cc-4372-a567-0e02b2c3d479";

​
Extracting Tracking ID from URLs

In your application, extract the tracking_id from URL parameters to maintain attribution throughout the customer journey:

// Mobile app or web application
const extractTrackingId = (url: string): string | null => {
  try {
    const urlObj = new URL(url);
    return urlObj.searchParams.get("$tracking_id");
  } catch (error) {
    console.error("Invalid URL:", error);
    return null;
  }
};

// Usage examples
const tracking_id = extractTrackingId(window.location.href);
// Or from deep link parameters in mobile apps
const tracking_id = extractTrackingId(incomingDeepLink);

// Store for later use in events
if (tracking_id) {
  // Store in session storage, app state, or local storage
  sessionStorage.setItem("masivo_tracking_id", tracking_id);
}

​
Using Tracking ID in Events

Once you have the tracking_id, include it in attribution data when sending events:

const sendEventWithAttribution = async (eventData: {
  type: string;
  customer_id: string;
  brand_id: string | null;
  [key: string]: any;
}) => {
  // Retrieve stored tracking ID
  const tracking_id = sessionStorage.getItem("masivo_tracking_id");

  const payload = {
    ...eventData,
    attribution: {
      tracking_id,
      // Add other attribution parameters as needed
      utm_source: "mobile_app",
      utm_medium: "push_notification"
    }
  };

  const response = await fetch(
    "https://app.masivo.ai/api/storefront/v1/behavior/events",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    }
  );

  return response.json();
};

// Example: Track purchase with attribution
await sendEventWithAttribution({
  type: "PURCHASE",
  customer_id: "customer-123",
  brand_id: "brand-456",
  order: {
    purchase_id: "order-789",
    value: 99.99,
    products: [
      {
        sku: "PROD-001",
        amount: 1,
        value: 99.99
      }
    ],
    payment_method: "CREDIT"
  }
});

​
2. UTM Parameters and Campaign Tracking

​
Understanding UTM Parameters

UTM parameters are standardized tags that help track the effectiveness of marketing campaigns:

​
utm_source

Identifies the traffic source:

  • "google" - Google search or ads
  • "facebook" - Facebook ads or posts
  • "email" - Email campaigns
  • "newsletter" - Newsletter campaigns
  • "organic" - Organic/direct traffic

​
utm_medium

Describes the marketing medium:

  • "cpc" - Cost-per-click advertising
  • "email" - Email marketing
  • "social" - Social media
  • "push" - Push notifications
  • "sms" - SMS campaigns

​
utm_campaign

Names the specific campaign:

  • "summer-sale-2024"
  • "new-user-onboarding"
  • "cart-abandonment-recovery"

​
utm_term

Used for paid search keywords:

  • "premium headphones"
  • "wireless earbuds"

​
utm_content

Differentiates ad variations:

  • "banner-ad-v1"
  • "email-button-cta"
  • "video-ad-30s"

​
Implementing UTM Tracking

const sendPurchaseWithUTMTracking = async (
  customerId: string,
  orderData: any,
  campaignInfo: {
    source: string;
    medium: string;
    campaign: string;
    term?: string;
    content?: string;
  }
) => {
  const attribution = {
    tracking_id: sessionStorage.getItem("masivo_tracking_id"),
    utm_source: campaignInfo.source,
    utm_medium: campaignInfo.medium,
    utm_campaign: campaignInfo.campaign,
    utm_term: campaignInfo.term,
    utm_content: campaignInfo.content,
    revenue: orderData.total,
    ad_provider: campaignInfo.source === "google" ? "google_ads" : "unknown"
  };

  const eventData = {
    type: "PURCHASE",
    customer_id: customerId,
    brand_id: orderData.brand_id,
    attribution,
    order: {
      purchase_id: orderData.id,
      value: orderData.total,
      products: orderData.items.map(item => ({
        sku: item.sku,
        amount: item.quantity,
        value: item.price
      })),
      payment_method: orderData.payment_method
    }
  };

  return await fetch(
    "https://app.masivo.ai/api/storefront/v1/behavior/events",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(eventData)
    }
  );
};

// Usage example
await sendPurchaseWithUTMTracking("customer-123", orderData, {
  source: "google",
  medium: "social",
  campaign: "spring-collection-launch",
  content: "carousel-ad-variant-a"
});

​
3. Revenue and Cost Attribution

​
Tracking Revenue Attribution

Revenue attribution helps measure the financial impact of marketing campaigns and track the revenue and cost at each step of the customer journey until completion, providing a complete view of campaign ROI:

const trackRevenueAttribution = async (
  customerId: string,
  purchaseData: {
    order_value: number;
    acquisition_cost: number;
    campaign_source: string;
  }
) => {
  const attribution = {
    tracking_id: sessionStorage.getItem("masivo_tracking_id"),
    revenue: purchaseData.order_value,
    cost: purchaseData.acquisition_cost,
    utm_source: purchaseData.campaign_source,
    utm_medium: "paid_advertising"
  };

  const eventData = {
    type: "PURCHASE",
    customer_id: customerId,
    brand_id: "your-brand-id",
    attribution,
    order: {
      purchase_id: `order-${Date.now()}`,
      value: purchaseData.order_value,
      products: [
        /* order products */
      ],
      payment_method: "CREDIT"
    }
  };

  return await sendEventWithAttribution(eventData);
};

​
Cost Tracking for Campaign Analysis

Track marketing costs to calculate ROI:

const trackCampaignCost = async (
  customerId: string,
  action: string,
  campaignCost: number
) => {
  const attribution = {
    tracking_id: sessionStorage.getItem("masivo_tracking_id"),
    cost: campaignCost,
    utm_source: "google_ads",
    utm_medium: "cpc",
    utm_campaign: "holiday-sale-2024",
    ad_provider: "google_ads"
  };

  const eventData = {
    type: action, // e.g., "ADD_TO_CART", "VIEW_PRODUCT"
    customer_id: customerId,
    brand_id: "your-brand-id",
    attribution
  };

  return await sendEventWithAttribution(eventData);
};

For more information about implementing campaigns and measuring their effectiveness, see the Journey Triggers Guide and Customer Audience Enrollment Guide.