Snapchat Ads

The Snapchat Ads Connector provides automated access to ad analytics via the Snapchat Marketing API.

Prerequisites

The Snapchat Marketing API uses access tokens to control access and authentication through OAuth.

For the connector to to access the API, add a Key through the Keys tab and choose the “Snapchat” credential type.

Provide a Key Name and then click the Connect button to obtain the OAuth credential.

Key Name
The value to use for the key property of your Switchboard Script (see below)

Scheduling

The Snapchat Ads connector can be scheduled to ingest data once per day at a user-defined hour and timezone.

By default, the connector will run once at 6am PT.

See Daily Scheduling for more information.

This connector supports repulls to accomodate the fact that Snapchat changes conversion metrics over a period of days after the initial reporting date. It is possible to specify the duration after which the data should be pulled again or “re-pulled” via the repull_days parameter.

This connector also allows importing the date-range backfills through the Switchboard UI.

Parameters

For full details on parameter values, see the Snapchat marketing API documentation.

organization_id
REQUIRED An Organization represents an brand, partner or ad agency, creation happens via Snap Business Manager; string
metrics
REQUIRED Affects campaign stats; string list
granularity
OPTIONAL Metrics granularity. Affects campaign stats; string, default = DAY
breakdown
OPTIONAL Object-level breakdown. Affects campaign stats; string
dimension
*OPTIONAL** Insight-level breakdown. Affects campaign stats; string list
swipe_up_attribution_window
OPTIONAL Attribution window for swipe ups. Affects campaign stats; string
view_attribution_window
OPTIONAL Attribution window for views. Affects campaign stats; string
conversion_source_types
OPTIONAL Conversion source breakout by platform. Affects campaign stats; string

Sample Switchboard Script


import bundle snapchat_bundle {
    type: "snapchat:campaign_bundle";
    key: "snapchat_ads_key";
    organization_id: "XXXXXXXXXX";
    granularity: "DAY";
    dimension: ["country"];
    breakdown: "adsquad";
    timezone: "America/Los_Angeles";
    metrics: [
        "impressions",
        "swipes",
        "quartile_1",
        "quartile_2",
        "quartile_3",
        "view_completion",
        "spend",
        "video_views",
        "attachment_quartile_1",
        "attachment_quartile_2",
        "attachment_quartile_3",
        "attachment_view_completion",
        "attachment_total_view_time_millis",
        "attachment_video_views",
        "story_opens",
        "story_completes",
        "shares",
        "saves",
        "total_installs",
        "conversion_purchases",
        "conversion_purchases_value",
        "conversion_save",
        "conversion_start_checkout",
        "conversion_add_cart",
        "conversion_view_content",
        "conversion_add_billing",
        "conversion_sign_ups",
        "conversion_searches",
        "conversion_level_completes",
        "conversion_app_opens",
        "conversion_page_views"
    ];

    // All ad accounts for the organization
    // https://marketingapi.snapchat.com/docs/#ad-accounts
    // https://marketingapi.snapchat.com/docs/#get-all-ad-accounts
    
   table ad_accounts using SNAPCHAT_ACCOUNTS_SCHEMA;

    // All ad squads for all ad accounts
    // https://marketingapi.snapchat.com/docs/#ad-squads
    // https://marketingapi.snapchat.com/docs/#get-all-ad-squads-under-an-ad-account
    
   table ad_squads using SNAPCHAT_AD_SQUADS_SCHEMA;

    // All campaigns for all ad accounts
    // https://marketingapi.snapchat.com/docs/#campaigns
    // https://marketingapi.snapchat.com/docs/#get-all-campaigns
    
   table campaigns using SNAPCHAT_CAMPAIGN_SCHEMA;

    // Campaign stats for all campaigns
    // https://marketingapi.snapchat.com/docs/#get-campaign-stats
    
   table campaign_stats using SNAPCHAT_CAMPAIGN_STATS_SCHEMA;
};

Schemas:

schema SNAPCHAT_ACCOUNTS_SCHEMA {
    id: string;
    name: string;
    updated_at: datetime;
    created_at: datetime;
    type: string;
    status: string;
    organization_id: string;
    currency: string;
    timezone: string;
    advertiser_organization_id: string;
    billing_center_id: string;
    billing_type: string;
    agency_representing_client: boolean;
    client_paying_invoices: boolean;
    funding_source_ids: json;
};

schema SNAPCHAT_AD_SQUADS_SCHEMA {
    id: string;
    updated_at: datetime;
    created_at: datetime;
    name: string;
    status: string;
    campaign_id: string;
    type: string;
    targeting: {
        regulated_content: boolean;
        demographics: json;
        interests: json;
        geos: json;
        segments: json;
    };
    targeting_reach_status: string;
    placement: string;
    billing_event: string;
    bid_micro: integer;
    auto_bid: boolean;
    target_bid: boolean;
    bid_strategy: string;
    lifetime_budget_micro: integer;
    start_time: datetime;
    end_time: datetime;
    optimization_goal: string;
    delivery_constraint: string;
    pacing_type: string;
    pixel_id: string;
};

schema SNAPCHAT_CAMPAIGN_SCHEMA {
    id: string;
    updated_at: datetime;
    created_at: datetime;
    name: string;
    ad_account_id: string;
    status: string;
    objective: string;
    measurement_spec: json;
    start_time: datetime;
    end_time: datetime;
    lifetime_spend_cap_micro: integer;
    buy_model: string;
};

schema SNAPCHAT_CAMPAIGN_STATS_SCHEMA {
    id: string;
    type: string;
    start_time: datetime;
    end_time: datetime;
    breakdown_stats: json;
    swipe_up_attribution_window: string;
    view_attribution_window: string;
    finalized_data_end_time: datetime;
};