SmartNews Ads Conversion API

This guide will walk you through the process of integrating with the SmartNews Ads Conversion API, designed to help advertisers share conversion data more reliably and securely with SmartNews Ads platform.

The Conversion API enhances campaign measurement accuracy and increases signal volume, leading to improved advertising performance.

Detailed Conversion API documentation >

Supported features

The Conversion API supports:

• Web and mobile app conversion events
• Raw postback sharing and attributed postback sharing
• Both deterministic and probabilistic attribution methods
• Customizable event properties and parameters
• Compatible with existing Pixel tracking and MMP integration

Getting started

Prerequisites

Before implementing the Conversion API, ensure you have:

• An active SmartNews Ads account
• For web campaigns: A SmartNews Pixel created in Event Manager
• For app campaigns: A Google or Apple app store ID and a Mobile Measurement Partner such as Adjust or AppsFlyer

Apply for API access

To start using the Conversion API:

1Submit an application through our application form.

2Provide your company and partner details together with your Pixel or app details.

• Submit one application per advertiser. All assets (Pixel and/or App Store ID) included in your application must belong to the same advertiser.
• If submitting multiple applications for different advertisers, please include the partner_name previously issued to you. Note that this process can take up to 14 days.
• Important: You need to create a Pixel Tag in Event Manager and include this in your application form. This Pixel Tag is used to verify postbacks.

3Wait for approval notification from the SmartNews team. Once approved, SmartNews will provide you with a partner name and access token.

• Currently, we only accept applications from our existing advertising partners.

Implementation

Once your application is approved, you’ll receive an email with your "Partner_Name" and "Authentication Token". Keep these credentials handy as they will be required for setting up your integration.

Web implementation

For web conversions, you’ll need to:

1Create a Pixel in Event Manager (required even if not using client-side tracking).

2Include your pixel_tag_id in your API calls, along with your partner name and access token as common request parameters.

3Set up server-side event tracking.

Example API call for web conversion:

{
    "action_source": "web",
    "event_name": "purchase",
    "pixel_tag_id": "9112675ff25eb25f580feb82",
    "event_source_url": "<http://www.example.com?store=abc>",
    "click_id": "UnoPeo4IDmEwnHepAAEA",
    "event_time": 1473668802,
    "properties": {
        "item_id": "product:10003938",
        "shop_id": "myshop",
        "event_value": 9.99,
        "currency": "USD",
        "quantity": 2
    }
}

Setting up postbacks using GET and third-party tracking tools

You can implement the Conversion API using either GET or POST requests. Here’s how to set up using GET requests with third-party tracking tools:

1Tracking URL Configuration:

The tracking URL you’ll use in SmartNews Ads Manager UI must include the click_id parameter and can include additional parameters:

<https://xyz.com/cf/r/67b6a149ff421a001274f089?click_id={click_id}&ad_id={ad_id}&campaign_id={campaign_id}&ad_group_id={ad_group_id}&ad_account_id={ad_account_id}>

Important

The `{click_id}` parameter must remain enclosed in curly brackets `{}`. SmartNews supports the following dynamic macros:

- {click_id}
- {ad_id}
- {campaign_id}
- {ad_group_id}
- {ad_account_id}.

For more details, see: SmartNews dynamic URL macros

2Postback URL Configuration:

Use the following format for your postback URL, replacing the highlighted parameters:

<https://log.smartnews-ads.com/conversion_api/v1/[REPLACE_with_partner_name]?action_source=web&pixel_tag_id=[REPLACE_with_Pixel_tag_id]&event_name=[Replace_with_Event_Name]&click_id=[REPLACE_WITH_CLICK_ID]>

• Partner_Name: The numeric value provided in your approval email (e.g., "9492446")
• Pixel_Tag_Id: The alphanumeric ID of your Pixel Tag created in Event Manager

• Event_Name: Choose from supported event types. Do not leave any empty spaces in the event name.
• Click_Id: The variable your tracking tool uses to collect click_id

Common click_id variables by platform:

• Voluum: {externalid}
• ClickBank: {ext_clid}
• Everflow: {sub1}
• RedTrack: {ref_id}
• ClickFlare: {external_id}
• Tune: {aff_click_id}
• DigiStore24: {cid}
• CAKE: #s2#

Example completed postback URL (using Voluum):

<https://log.smartnews-ads.com/conversion_api/v1/97559088?action_source=web&pixel_tag_id=69be6b63fe1f47449c3aa6d7&event_name=Purchase&click_id={externalid}>

Example of Voluum traffic source setup screen using SmartNews parameters:

App implementation

For app conversions, you’ll need to:

1Provide your app store ID and platform in your API calls, along with your partner name and access token as common request parameters.

2Implement server-side event tracking.

Example API call for app conversion:

{
    "action_source": "app",
    "event_name": "Purchase",
    "store_id": "appstore.example.android",
    "platform": "Android",
    "click_id": "UnoPeo4IDmEwnHepAAEA",
    "event_time": 1473668802,
    "properties": {
        "item_id": "product:10003938",
        "shop_id": "myshop",
        "event_value": 9.99,
        "currency": "USD",
        "quantity": 2
    }
}

FAQ

Q: Can I use Conversion API alongside Pixel tracking?

A: Yes, the Conversion API can work alongside Pixel tracking or MMP integration. SmartNews automatically deduplicates conversions from these sources using a best-effort approach.

Q: Do I need to implement Pixel tags if I’m using the Conversion API for app conversions?

A: No, you don’t need to implement Pixel tags for tracking conversions in your app. However, you will need to select a Mobile Measurement Partner (MMP).

Q: What’s the difference between raw and attributed postbacks?

A: Raw postbacks contain conversion data without detailed attribution information, while attributed postbacks include your own attribution results, typically including the click_id that led to the conversion.

Q: Do you support passing payout or event_value in requests?

A: Yes, but only in POST requests and not GET requests. We are working to add support for this in GET requests as well.

Q: Will my authorization token for Conversion API work for Marketing or Reporting API as well?

A: No, you need to fill out a different form and get separate approval for Marketing API. Refer to the Marketing API help page and submit the application form.

Related articles

• Conversion API Developer Documentation: Developer Documentation
• SmartNews Ads API Terms of Use:
  • Terms of Use (English)
  • Terms of Use (Japanese)

• Marketing API Resources:
  • Marketing API Documentation
  • Marketing API Developer Guide

For additional assistance or questions about implementation, please contact your SmartNews Ads representative.