# Documentation Learn the concepts of Freshpaint and how to use them effectively Freshpaint is a tool for teams with limited technical resources to manage and control their customer data. Freshpaint enables non-technical users to set up their favorite analytics and marketing tools with limited input from a technical user. ## Common Use Cases {% content-ref url="/pages/-MA7fP-NORUW1NBgRHKI" %} [Add Autotrack to your website to collect data from your users](/readme/guides/quickstart) {% endcontent-ref %} {% content-ref url="/pages/ItrQh2J3uAEyLEBIDNwz" %} [HIPAA Mode](/readme/hipaa-mode) {% endcontent-ref %} {% content-ref url="/pages/t0EpZDjQsQx3O8Bvouup" %} [Send historical data to any destination with Time Machine](/readme/guides/time-machine) {% endcontent-ref %} ## Getting Started Learn what you have to do to get your Freshpaint account ready to send data to your destinations. {% content-ref url="/pages/-MA7fXEzWqQH8ON4yjiu" %} [Building Out Your Account](/readme/building-out-your-account) {% endcontent-ref %} ## Everything else Learn more about what Freshpaint has to offer here: {% content-ref url="/pages/-MA7m48mwHOs5Ap1-kee" %} [Overview of Features](/readme/overview-of-features) {% endcontent-ref %} # What is Freshpaint? \ At Freshpaint, we’re helping healthcare companies grow without compromising patient privacy. Our platform makes it possible to use modern analytics and marketing tools while staying HIPAA compliant. Behind the scenes, we’re solving complex data problems so healthcare marketers can move fast, reach more people, and expand access to care. ### Traditional Customer Data Platforms Aren’t Designed For Healthcare Customer Data Platforms promise to make sending data to any tool easy. That’s a problem for healthcare marketers because regulations around patient privacy prohibit sharing sensitive information. Being a healthcare marketer requires more control over the data that’s shared. That’s where Freshpaint comes in ### HIPAA compliant at its core Freshpaint’s Business Associate Agreement is more than just a piece of paper. That’s because it’s combined with our industry-first Healthcare Privacy Platform that helps prevent Protected Health Information from being shared with all your non-HIPAA compliant tools. ### Instrument your site without writing code Most analytics tools require you to write code every time you want to collect a new piece of data. Once installed, Freshpaint automatically captures every click, pageview, and form submission. This makes it possible for non-technical users to route data from Freshpaint into any marketing or analytics tool. ### Block Data By Default Instead of requiring you to filter out sensitive data, Freshpaint’s default state doesn’t share anything at all. Freshpaint’s unique opt-in approach is the safest way to prevent inadvertently sharing protected health information with marketing tools that aren’t HIPAA-compliant. ### Stitch Together Multiple Visitor Sessions Analytics tools require identifiers, like IP addresses, to connect unique visitors to individual sessions. Since HIPAA regulations prohibit sharing identifiers, how do you get a complete view of the visitor journey? That's where Freshpaint comes in. # HIPAA Mode Freshpaint provides several features to restrict and manage Protected Health Information (PHI) in your customer data. HIPAA mode is a feature that Freshpaint provides to give customers full control over what [Protected Health Information](https://www.hhs.gov/answers/hipaa/what-is-phi/index.html) (PHI) is sent to their destinations. Freshpaint allows you to configure explicit lists of properties, called allowlists, for each of your destinations so you opt into what you send and how you send it. ## What is PHI? PHI is the combination of Personal Identifiable Information (PII) and health information. Examples of PII include: * Names * IP Addresses * Non-anonymized user IDs * Emails Examples of health information include: * Diagnoses * Treatment information * Medical test results * Prescription information ## Enforced Allowlists {% embed url="" %} Watch this video to learn how to use allowlists in Freshpaint {% endembed %} The Enforced Allowlists feature allows you to send properties classified as PHI to your HIPAA-compliant destinations, and send only non-PHI properties to non-HIPAA compliant destinations. Freshpaint does this by allowing you to specify a list of properties that are known to not contain PHI. Whenever Freshpaint sees a property that is not in this allowlist, Freshpaint will remove the property before sending the event to non-HIPAA compliant destinations. ### Project Allowlist Navigate to the Project Allowlist page to specify which properties are not considered PHI for your Freshpaint Project. {% hint style="info" %} Properties allowed at the Project level will be automatically applied to all Destination Allowlists. {% endhint %}
### Destination Required Properties In addition to the Project Allowlist, each destination that supports server-side connection mode has its own allowlist. In order for Freshpaint to be able to send data to the destination, you must allow each of the required properties. These settings will not affect any other destination.

Some destinations offer Required Properties for you to add to the allowlist

For example, the Google Ads destination requires the `$gclid` and `conversion_label` properties. Without these properties, Google Ads will not be able to attribute conversions to your ad campaigns, so the destination will not be able to function.

$gclid and conversion_label are Required Properties for Google Ads

### Destination Recommended Properties Certain destinations have additional functionality that is controlled by certain event properties. Freshpaint indicates these properties as "Recommended" and describes the functionality they enable.

Some destinations offer Recommended Properties for you to add to the allowlist

For example, to enable the Conversions Report for Google Analytics 4, you would need to allow the `conversion` property.

To enable the Conversions Report in Google Analytics 4, allow the conversion property

### Destination Allowlist In addition to required and recommended properties, each destination that supports server-side connection mode has a full allowlist, similar to the Project Allowlist. You can use this advanced feature if you need to add properties to the destination's allowlist that are not covered by the Required or Recommended properties. {% hint style="info" %} All of the Required and Recommended Properties that you have allowed will be shown on the Destination Allowlist. {% endhint %}

Navigating to the Destination Allowlist

Add properties to the destination's allowlist if they're known to be safe to send to that specific destination. For example you may add the Facebook Ad Click ID to the allowlist for Facebook Conversions API in order to track conversions from your ad campaigns.

The Facebook Conversions API Destination Allowlist

{% hint style="warning" %} Required Properties, Recommended Properties, and Destination Allowlists are available in the latest version of Freshpaint HIPAA Mode. Contact to learn more. {% endhint %} ### Built-in Properties Freshpaint captures a number of properties automatically for each event, for example the URL of the page on which the event occurred. These are known collectively as [built-in properties](/reference/faqs/what-data-does-freshpaint-collect/autotrack#properties-captured). You can use the PHI Allowlist to specify which ones are known not to contain PHI. {% hint style="warning" %} Built-in Property Allowlisting is available in the latest version of Freshpaint HIPAA Mode. Contact to learn more. {% endhint %}

Built-in and Custom Property Allowlist

Most of these built-in properties are documented under [What Data Does Freshpaint Collect?](/reference/faqs/what-data-does-freshpaint-collect/autotrack#properties-captured). Special attention should be paid to **URL, UTM Parameters, and Other Query Parameters**. Suppose an event occurs on `http://shoes.com/the/best/shoe?utm_term=shoes&page=2`. The following table illustrates the value of the `$current_url` property under different allowlist configurations.
URLUTM TermOther Query Parameters$current_url propertyNotes
falsefalsefalsehttp://shoes.com/url-redacted-by-freshpaintWhen URL is not on the allowlist, Freshpaint will still send the domain name to destinations, along with a fake path that indicates the real path was redacted.
truefalsefalsehttp://shoes.com/the/best/shoeThe domain name and path are preserved but all query parameters are removed
truetruefalsehttp://shoes.com/the/best/shoe?utm_term=shoesThe page query parameter is removed.
truefalsetruehttp://shoes.com/the/best/shoe?page=2Since Other Query Parameters are allowlisted, any query parameters that aren't UTM parameters are preserved, in this case, page=2. The utm_term query parameter is removed.
truetruetruehttp://shoes.com/the/best/shoe?utm_term=shoes&page=2The entire URL is allowed to be sent to the destination.
### Custom Properties Events may have additional custom properties beyond those automatically captured by Freshpaint, for example if you're using [Freshpaint Web SDK Reference](/reference/developer/freshpaint-sdk-reference#addeventproperties) to add data layer properties to your events. You can use the PHI Allowlist to specify the custom properties that are known not to contain PHI. ### User & Group Properties There are separate allowlists for user properties, which are attached to [`freshpaint.identify`](/reference/developer/freshpaint-sdk-reference#identify) calls, and for group properties, which are attached to [`freshpaint.group`](/reference/developer/freshpaint-sdk-reference#group) calls.

Event, User, and Group Allowlists

## ID Masking ID Masking allows you to [identify users](/readme/setting-up-identify) in Freshpaint without sending the identifier to non-HIPAA compliant destinations. Freshpaint does this by *hashing* the user identifier before sending events to non-HIPAA compliant destinations. This anonymizes the user identifier, while still associating events with a single identified user and preserving functionality like identity resolution. Here's an example. Suppose you identified a user by their email address: ```javascript freshpaint.identify("some_distinct_id", { "email": "ada.lovelace@example.com", "browser": "Chrome" }); ``` Masking would send values like `ada.lovelace@example.com` in a hashed form, scrambled in such a way that a reader at the destination will be unable to determine the original value. This hashing is consistent for a given value. If `ada.lovelace@example.com` is hashed into `iuUwhqIm1kEriZsVlu5TsGgX6/y5Pwfn`, then you can count on it being that value every time in your destinations. ID Masking is automatically performed on builtin user identifiers for non-HIPAA compliant destinations. To turn on ID Masking for additional properties, you must configure the allowlist for your destination. Add the property you want to allow, then check the `Hashed?` option.
{% hint style="info" %} Freshpaint uses the [SHAKE3 hash algorithm](https://en.wikipedia.org/wiki/SHA-3) for ID masking {% endhint %} ## Server-side Destinations Freshpaint's HIPAA mode requires your destinations be configured with a server-side connection. If one of your destinations only supports a client-side connection, you will not be able to use them in HIPAA mode. ## Restricting PHI without HIPAA mode enabled You may want to send events to a non-HIPAA compliant destination without applying ID Masking or Allowlists. This might be the case when: * You want to send events to a non-HIPAA compliant destination that only supports Client-side connection mode, so you need to disable HIPAA mode to use the client-side destination. {% hint style="success" %} Example: you want to send events to Hotjar, which only supports client-side connections. {% endhint %} * You want to send events to a non-HIPAA compliant destination, and the destination needs the original user identifier, so you need to disable ID masking. {% hint style="success" %} Example: you want to send events to your email marketing platform, and you need to preserve the user's email address. {% endhint %} To avoid sending PHI to a non-HIPAA compliant destination, you must restrict PII, health information, or both. Note that this restriction is scoped to all API calls made for a user. For example: * You attach PII (but not health information) to an anonymous user in a destination with a `Freshpaint.identify()` API call * Later on, you send a `Freshpaint.track()` API call containing health information (but not PII) to the same destination for this anonymous user You're still sending PHI to the destination, since the destination has received both PII and health information for the same user, even though this information was received in different requests. When determining whether a destination may collect PHI, it's important to understand exactly what metadata and properties a destination collects, and whether these metadata and properties contain PII or health information. For example, the Freshpaint [Bing Ads](https://help.ads.microsoft.com/#apex/3/en/53056/1/#exp151) destination, when configured in client-side connection mode, collects IP addresses, Freshpaint event names, and page URLs (alongside other metadata). Because an IP address is PII, it's important to ensure the event names and page URLs collected by Bing Ads do not include health information. If you're unsure whether one of your destinations is collecting PHI, don't hesitate to reach out to . And of course, you should always consult with your legal team. # Building Out Your Account This series of guides will walk you through everything you need to completely setup your account. This series consists of the following guides: ## Setting up Your Destinations Destinations are the places Freshpaint sends data to. Setting up Your Destinations walks you through how to setup a destination. {% content-ref url="/pages/-MAbiLEGmIYGWwOFen2x" %} [Setting up Your Integrations](/readme/setting-up-your-destinations) {% endcontent-ref %} ## Setting up Your Events Events are how you control data as it flows through Freshpaint. By defining events, you are able to select specific types of data that are important to you and control which destinations they are sent to. This guide walks you through the different ways you can create events in Freshpaint. {% content-ref url="/pages/-MAbi6\_nuLVkM18dgjUf" %} [Setting up Your Events](/readme/setting-up-your-events) {% endcontent-ref %} ## Setting up Identify Identify is how you stitch data for a user from multiple different places together. This guide walks you through how to attach information to users. {% content-ref url="/pages/-MAbiGEe2YpMYAFwE0vv" %} [User Identification](/readme/setting-up-identify) {% endcontent-ref %} ## Setting up Properties Out of the box Freshpaint collects a decent amount of data, but there may be some additional contextual information you want to attach to your events. The Setting up Properties guide walks you through how to attach more information to your events. {% content-ref url="/pages/-MAbiTXcTQpT1UTK\_7K5" %} [Setting up Properties](/readme/setting-up-properties) {% endcontent-ref %} # Onboarding Readiness Guide Leverage this guide ahead of your kick-off call with Freshpaint to ensure we maximize success through the implementation process. ### How should this guide be used? **Your journey with Freshpaint begins here!** This guide is your roadmap to a smooth and efficient Freshpaint onboarding experience. Use it to align your internal teams, gather the necessary technical and compliance approvals, and ensure all required platforms and credentials are ready before implementation begins. Share this guide with key stakeholders such as engineering, product, marketing, and compliance to ensure everyone is prepared for a successful launch! 🚀 Freshpaint's safe by default approach to data sharing gives customers control over what data to share with analytics and marketing tools. This enables effective analytics and marketing approaches while remaining HIPAA compliant. ### Onboarding Checklist :white\_check\_mark: Before diving into Freshpaint's onboarding process, it's essential to ensure your team is fully prepared. Completing these steps ahead of time will streamline your setup, reduce delays, and accelerate your time to value with Freshpaint. * [ ] Identify and mobilize your Freshpaint onboarding and implementation stakeholders. This should include: Freshpaint admin(s), onboarding project manager, marketing and performance stakeholders including agency partners, and legal / privacy / compliance. * [ ] Gather necessary information for implementation setup and access requirements. * [ ] Review the Freshpaint implementation scope details for your services tier. * [ ] Ensure your legal/compliance team has reviewed Freshpaint's required and recommended Allowlist properties prior to kickoff. * [ ] Review Freshpaint's [product documentation](https://documentation.freshpaint.io/) to familiarize yourself with our implementation quick start guides and best practices. * [ ] Review [Freshpaint's Privacy Hub](https://www.freshpaint.io/healthcare-privacy-hub) for articles, videos, and thought leadership about healthcare privacy. ### Who should be involved in onboarding? Successful Freshpaint onboarding requires collaboration across multiple teams within your organization. From technical implementation to compliance approvals, each stakeholder plays a key role in ensuring a smooth setup. The table below outlines the primary participants and their responsibilities, helping you align the right people from the start. Engaging these teams early will streamline the process and accelerate your time to value with Freshpaint. #### Key Stakeholder Roles
Key StakeholderDescriptionLevel of EffortStage/MileStone
Executive Sponsor

Champions Freshpaint strategically, aligning

it with business goals, securing resources,

and removing blockers to drive its adoption

and success.

1 to 2

hours

Kickoff(s)

Launch Validation

Freshpaint
Admin/Owner

Authorized to manage Freshpaint projects,

environments, role-based access, and

configuration updates.

4 to 6

hour

All
Project Manager

Oversees implementation planning,

execution, and delivery, coordinating teams

and timelines to achieve project goals

efficiently.

10 to 20

hours

All

Performance

Stakeholders

(Internal or Agency

Partner)

SME(s) of advertising and analytics

platforms. Familiarity with key performance

indicators (KPIs), ensuring alignment with the

context and expected outcomes of the data

captured by Freshpaint.

6 to 10

hours

Implementation

Pre-launch

Validation

Launch Validation

Legal/Compliance

Ensures processes, data handling, and

systems comply with HIPAA, safeguarding

privacy and security, advising on risk,

overseeing audits, and upholding legal

standards.

1 to 2

hours

Implementation

Pre-launch

Validation

### Implementation Setup & Access Requirements This section outlines the common platforms we integrate with, the necessary credentials for configuration, and level of access that your Freshpaint onboarding resource may require. Having these ready in advance will help your onboarding team configure Freshpaint efficiently and avoid setup delays. Note: This table includes the most commonly configured destinations. For a full list of supported destinations and associated quick start guides, please visit .
PlatformConfiguration RequirementsRequested Access for Freshpaint
Google Tag Manager*
  • Access to relevant container(s)
  • Audit tags - pause/remove tags no longer in use

*only required if maintaining use of

GTM with Freshpaint

Edit
Google Analytics
  • Your Google Analytics Measurement ID
  • A test property in GA4 to validate data in parallel with your native setup (instructions)
Read/View
Google Ads
  • Your Google Ads Conversion ID
  • Conversion Actions configured in your Google Ads account
Read/View
Meta Ads

  • Your Facebook Pixel ID and

    Access Token

Read/View
Microsoft (Bing) Ads
  • Your Microsoft Ads UET Tag ID
Read/View
### Required & Recommended Allowlist Properties Before onboarding, it's essential to review Freshpaint's recommended Allowlist properties with your legal and compliance teams. This review ensures alignment on the data that will be shared with your marketing and analytics tools during setup and configuration. By confirming these selections in advance, you can help streamline the implementation process and ensure Freshpaint is configured to meet your organization's data governance standards. #### Required Properties Freshpaint's server-side connection mode may require destination-specific properties indicated as "Required" that are essential for functionality. #### Recommended Properties Destinations may also have additional functionality that is controlled by certain event properties. Freshpaint indicates these properties as "Recommended" and describes the functionality they enable. [Click here for Freshpaint's Destination Allowlist overview](https://6516988.fs1.hubspotusercontent-na1.net/hubfs/6516988/Freshpaint%20Required%20and%20Recommended%20Data%20Properties.pdf) ### What to expect from your Freshpaint Onboarding Your Freshpaint onboarding is designed to provide hands-on support, technical guidance, and best practices to ensure a smooth and successful implementation. Here's what you can expect: * **Dedicated Onboarding Support** – A Customer Success Engineer will guide you through the entire onboarding journey, ensuring you stay on track. * **Best Practices & Recommendations** – Expert guidance on setting up your Freshpaint account for optimal tracking and data governance. * **Technical Support & Configuration** – Assistance with event tracking, tool integrations, and troubleshooting to ensure everything is set up correctly. * **Ongoing Customer Support** – Beyond onboarding, your Freshpaint team includes your named Account Manager and Freshpaint's technical support staff. #### Key Implementation Milestones {% columns %} {% column width="50%" %} * [x] **Partnership Kickoff** Introduction to the partnership, understand key milestones in Freshpaint's customer journey, and create your success plan. * [x] **Working Sessions** These sessions are essential for ensuring a successful implementation and require active participation from your team. * [x] **Launch Validation** Review onboarding milestones and success criteria, and align on next steps for a successful partnership. This marks the completion of you onboarding engagement with Freshpaint. {% endcolumn %} {% column width="50%" %} * [x] **Implementation Call** Introduction to implementation, confirmation on initial scope and requirements, and jobs to be done. * [x] **Technical Enablement** A training session for Freshpaint Admin/Owner(s) on account setup, configuration, and best practices. * [x] **Project Management** Your Freshpaint onboarding includes regular status emails and a shared project tracker, providing clear visibility into progress, key milestones, and outstanding implementation tasks. {% endcolumn %} {% endcolumns %} ### Freshpaint Standard Onboarding Scope #### Level 1 Support & Services *Onboarding scope to be completed within 6 months of implementation kickoff*
Onboarding DeliveryDescription
Maximum Projects / Domains1

Google Tag Manager - Tag

Migration

All supported tags included (based on contract

entitlements)

Net New Event Tags / Freshpaint

Event Creation

Up to 5 Events
Onboarding Milestones

1 x Implementation Call (60 min)

5 x Working Sessions (60 min)

1 x Technical Enablement (60 min)

1 x Launch Validation (60 min)

Destinations / EntitlementsAnalytics, Direct-response Ads (Google, Meta)
Call TrackingCallRail (if applicable)
Project Management

Optional Bi-Weekly Syncs (30 min)

Weekly Email Status Updates

Monday.com Onboarding Tracker

#### Level 2 Support & Services *Onboarding scope to be completed within 6 months of implementation kickoff*
Onboarding DeliveryDescription
Maximum Projects / DomainsUp to 2

Google Tag Manager - Tag

Migration

All supported tags included (based on contract

entitlements)

Net New Event Tags / Freshpaint

Event Creation

Up to 10 Events
Onboarding Milestones

1 x Implementation Call (60 min)

8 x Working Sessions (60 min)

2 x Technical Enablement (60 min)

1 x Launch Validation (60 min)

Destinations / Entitlements

Analytics, Direct-response Ads (Google,

Facebook, Microsoft, TikTok, LinkedIn,

Pinterest, and X)

Additional Feature SupportEmbedded Video, Web Tracker Monitoring
Call TrackingCallRail or Invoca (if applicable)
Project Management

Weekly Syncs (30 min)

Weekly Email Status Updates

Monday.com Onboarding TrackerMaximum Projects / Domains

#### Level 3 Support & Services *Onboarding scope to be completed within 6 months of implementation kickoff*
Onboarding DeliveryDescription
Maximum Projects / DomainsTo be scoped with customer

Google Tag Manager - Tag

Migration

All supported tags included (based on contract

entitlements)

Net New Event Tags / Freshpaint

Event Creation

To be scoped with customer
Onboarding Milestones

1 x Implementation Call (60 min)

Ad Hoc Working Sessions (60 min)

2 x Technical Enablement (60 min)

1 x Launch Validation (60 min)

Destinations / Entitlements

Analytics, Direct-response Ads (Google,

Facebook, Microsoft, TikTok, LinkedIn,

Pinterest, and X), GCM 360 Floodlight support,

Demand-side platform support

Additional Feature Support

Embedded Video, Embedded Maps, Web

Tracker Monitoring, SSO, RBAC

Call TrackingCallRail or Invoca (if applicable)
Project Management

Weekly Syncs (30 min)

Weekly Email Status Updates

Monday.com Onboarding Tracker

Named Customer Success Engineer

# Overview of Features A high-level overview of Freshpaint's main features. ## Sources The sources page is where you handle getting data into Freshpaint. ![](/files/-MAm5-EqWiIo721vR0xD) See the [docs on sources](/integrations/sources) for more information about the different sources Freshpaint supports and how to set them up. ## Destinations The destinations page is where you control where the data in Freshpaint gets sent to. ![](/files/-MAm5_3-DQG6aMLd4UvW) Freshpaint supports three kinds of destinations: * Apps - These are SaaS tools that will process your data in some way. * Warehouses - These are destinations that are data warehouses. They give you the flexibility to directly query your data. * Advertising - These are destinations that allow you to target ads to specific users. For more information about the different sources Freshpaint supports and the data you can send to them, see the [docs on destinations](/integrations/destinations). ## Transformations Transformations lets you modify your events before they are sent to a destination. ![](/files/-MLOH8Pn9ioPn9fH06fj) With transformations, you can rename events, rename properties, cast a string to a number, and more, before your data is sent to a destination. For more information, check out the [transformations docs](/admin-panel/transformations). ## Event Library The event library is where you manage what data gets sent to what destinations. ![](/files/-MAm6cmjCkR-BrtbG3Pw) With the event library, you can view all of your existing event definitions, make changes to them, and control which events are sent to which destinations. For more information about the event schema dashboard see the [event library docs](/admin-panel/events). ## Liveview Liveview is how you can debug and inspect your Freshpaint instrumentation. ![](/files/-MAS2dbpTH8VZ_zDrKCy) With liveview, you can see all the raw actions your users are performing on your site as well as when a specific event definition is performed on your site. You can even use live view to define events based on the raw actions performed. See the [docs on liveview](/admin-panel/investigate-testing-and-debugging/liveview) for more information. ## Trace View The Trace viewing tools lets you see how Freshpaint processed your users' events. We currently have two tools that let you inspect and discover what happened when processing your events: (1) Trace View Summary: This tool lets you see a summary view of all the events that happened in a particular time frame.

The Trace View Summary tool can be found on the Left main menu, under the "INVESTIGATE" section. Clicking the "VIEW" button on a Trace takes you to the second tool: the Trace Details View.

(2) Trace Details View: This tool lets you drill down into a particular trace and view each step.

The Trace Details View is accessed through the Trace View Summary tool. By clicking the "VIEW" button in the Trace View Summary, you are taken to an individual trace.

To see more information about the Tracing tools and how to use them, see the [docs on Tracing](/admin-panel/investigate-testing-and-debugging/traces) for more information. ## Visual Tagger The visual tagger provides a point and click interface for defining events. You don't have to write code to use it! ![](/files/-MASZFecErGrHcbkBVcA) You just click on the part of your page you want to create an event definition for and the visual tagger will create it for you. See the [docs on the visual tagger](broken://pages/-MA7m_EuXnptGT2gCPpE) for more information. ## Time Machine The time machine lets you send old data that matches a newly created event definition to a destination. Freshpaint automatically collects every user action on your site once installed. If you create a new event definition six months after installing, you can use the time machine to send every user action ever performed on your site that matches the event definition to a destination. See the [docs on the time machine](/admin-panel/events/time-machine) for more information. ## Teams Page The teams page is where you can invite new users to your Freshpaint account and see who the members of your team are. ![](/files/-MAm9Srj0ccgy6Zoyxx9) See the [docs on the teams page](/admin-panel/teams) for more information. # Guides Here you'll find a collection of guides to use cases that we've found our customers have. Don't see something here? Let us know! # Add Autotrack to your website to collect data from your users Automatically track data on your website and send to your customer and marketing tools This guide will walk you through setting up Autotrack for your website. Once completed you'll be sending data from your website into a Freshpaint destination. Throughout this guide, we will use Google Analytics as the example, but the same steps work with any other destination supported by Freshpaint. This quickstart guide is made up of three sections: {% content-ref url="/pages/-MA83ZkLUvNKjT9Y4LxX" %} [Installing the Freshpaint Javascript SDK](/readme/guides/quickstart/installing-freshpaint) {% endcontent-ref %} {% content-ref url="/pages/-MA8cXAqP5IdBZ4iUnaf" %} [Configuring a Destination](/readme/guides/quickstart/configuring-a-destination) {% endcontent-ref %} {% content-ref url="/pages/-MA83dFVSQy\_15USZUz5" %} [Labeling User Actions](/readme/guides/quickstart/labeling-user-actions) {% endcontent-ref %} ## User Identification Once you have confirmed that Freshpaint is successfully installed, [setting up identify ](https://documentation.freshpaint.io/readme/setting-up-identify)is how you send information to Freshpaint and your destinations about who your users are. # Installing the Freshpaint Javascript SDK Installing the Freshpaint Javascript SDK to the production website has to be done by an engineer. It usually takes about five minutes to install. For deploying to production you should [invite a technical teammate](/admin-panel/teams) to your account and have them install Freshpaint. Once installed (either locally or on production), a non-technical user can use Autotrack within the [Web source ](/integrations/sources/web)to control and manage data without assistance from a technical user. ### Installing the Freshpaint SDK Directly Onto Your Site To install Freshpaint, go to the [sources page](https://app.freshpaint.io/sources) in Freshpaint:
From the sources page click on **configure** next to the [Web source](/integrations/sources/web). This will pull up the code for the Freshpaint SDK:
Copy the snippet into the `` of your site. That's it! {% hint style="info" %} If your application uses [Next.js](https://nextjs.org/docs/basic-features/script), you will need to add an **id** attribute to the script tag of the Autotrack snippet, such as \ ``` ### Location Services API Some more interactive web experiences require the use of location services APIs. Freshpaint provides access to a number of location services APIs that are used for Geocoding, Reverse Geocoding, and location search. For example, a website developer may want to organize location results by distance from a website visitor. This might be done through requesting a zip code from the user. The location API allows the website to request the coordinates of a zip code, and then knowing the latitude and longitude of both the zip code and locations allows code to be written that will reorganize the results based on distance. Freshpaint provides access to the [Amazon AWS Location Service](https://aws.amazon.com/location/) for providing location APIs to a website visitor. ## Using the Location Services API Freshpaint provides access to the Amazon AWS Location Services by accessing Freshpaint services. So in the amazon location services docs, you might see: `/v2/autocomplete?key=Key` You would instead use ``` https://freshpaint-hipaa-maps.com/v2/autocomplete?token=YOUR-ENVIRONMENT-ID-HERE ``` See on how to find your environment ID and replace `YOUR-ENVIRONMENT-ID-HERE` with the token for your Freshpaint environment. {% hint style="info" %} The AWS API Docs indicate the use of an API Key as the ?key=Key parameter on their examples. When using the location services with Freshpaint you instead use ?token=YOUR-ENVIRONMENT-ID-HERE to access the location services from Freshpaint. The key parameter is not used when accessing the location services through freshpaint-hipaa-maps.com {% endhint %} ### Common Functions #### Please refer to the [AWS Location Services Places documentation](https://docs.aws.amazon.com/location/latest/APIReference/API_Operations_Amazon_Location_Service_Places_V2.html) for details on how to use the following actions: * [Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html): completes potential places and addresses as the user types, based on the partial input. * [Geocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Geocode.html): converts a textual address or place into geographic coordinates. * [GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html): finds a place by its unique ID. A `PlaceId` is returned by other listed actions. * [ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html): converts geographic coordinates into a human-readable address or place. * [SearchNearby](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_SearchNearby.html): queries for points of interest within a radius from a central coordinates, returning place results with optional filters such as categories, business chains, food types and more. * [SearchText](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_SearchText.html): searches for geocode and place information. Can use the query ID from `Suggest` action to run a follow up query. * [Suggest](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html): provides intelligent predictions or recommendations based on the user's input or context, such as relevant places, points of interest, query terms or search category. ## Examples The example site has a full working demo that you can inspect and customize to your needs. {% embed url="" %} A demo site showing the Freshpaint map connected to clickable location cards. When you click on a location card, the map automatically focuses on the location. When you click on a pin, the location cards automatically scroll to the selected location. {% endembed %} {% hint style="info" %} You can use view-source in your browser to see how the demo was built in pure Javascript and HTML. {% endhint %} ### Map Setup: Vanilla JS Freshpaint uses MapLibre as an open-source renderer to display the map. You will need to load MapLibre and its stylesheet. ```html ``` #### Creating a Map 
// Styles affect how the maps look:
// We currently support the following styles:
//   "standard-light":      colorized, typical map style
//   "standard-dark":       colorized, typical dark map style
//   "visualization-light": grayscale, elegant black and white style
//   "visualization-dark":  grayscale, elegant dark black and white style
const style = "standard-light" 

// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id
const envId = "YOUR-FRESHPAINT-ENVIRONMENT-ID"

const map = new maplibregl.Map({
  container: "map",
  style: `https://freshpaint-hipaa-maps.com/${envId}/${style}/style-descriptor`,

  // longitude and latitude of the map's origin
  // Note: this is backwards compared to google maps
  center: [-87.6800, 41.8500],

  // Zoom levels (rough descriptions):
  // 15 : a close street view
  // 13 : city neighborhoods
  // 11 : entire region (Chicagoland)
  zoom: 13,
});

// This adds a toolbar for zooming an panning:
// + : zoom in
// - : zoom out
// compass for rotating (e.g. north facing up or south facing up)
map.addControl(new maplibregl.NavigationControl(), "top-left");
#### Adding pins with popups 
// Note: LngLat is reversed from google maps which does LatLng.
const markers = [
  {
    "LngLat": [-87.7276, 41.7919],
    "Header": "UI Health",
    "Href": "https://hospital.uillinois.edu/"
  },
  {
    "LngLat": [-87.69738, 41.85505],
    "Header": "Saint Anthony Hospital",
    "Href": "https://sahchicago.org/"
  }
];

// You can customize popups with arbitrary HTML
// Here, we just do a simple header and link to the website
const newPopup = (m) => new maplibregl.Popup({ offset: 25 })
                                      .setHTML(`<div>
                                                    <h3>${m.Header}<\/h3>
                                                    <a href="${m.Href}">${m.Href}<\/a>
                                                <\/div>`)

markers.forEach((m) => {
  const popup = newPopup(m);
  const marker = new maplibregl.Marker({color: "#808080"})
                               .setLngLat(m.LngLat)
                               .setPopup(popup)
                               .addTo(map);
});
#### Full working example See the working demo at for a demo with the Freshpaint map connected to clickable location cards. This demo shows how to add on-click handlers to customize behaviors when users click on Map pins. It also shows how to link external actions to the Map (e.g. so on-click outside of the map cause the map to recenter). ### Location Search Setup: Freshpaint also offers a HIPAA-compliant Location search service that finds location matches to user inputs. We offer a backend that can be used with your autocomplete frontend of choice.

Example location autocomplete

#### API Details The API is accessible at 
// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id

POST `https://freshpaint-hipaa-maps.com/v2/autocomplete?token=YOUR-ENVIRONMENT-ID-HERE`
#### Request body Because we use AWS Location Services, a full account of all supported features, and inputs can be found here: {% embed url="" %} #### Sample CURL request ```bash // Replace the TOKEN variable with your freshpaint environment ID // Go to the URL below to see how to find your Freshpaint Environment ID // https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE" curl 'https://freshpaint-hipaa-maps.com/v2/autocomplete?token=$TOKEN' \ -H 'accept: application/json' \ -d '{"QueryText":"chicago", "BiasPosition": [-87.69420, 41.86181], "MaxResults":8,"Filter":{"IncludeCountries":["USA"]}}' ``` ### Reverse Geocoding Setup: Freshpaint also offers a HIPAA-compliant Reverse Geocoding API that allows you to look up an address based on Latitude and Longitude. #### API Details The API is accessible at ``` # Replace the environment ID below with your freshpaint environment ID # Go to the URL below to see how to find your Freshpaint Environment ID # https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id POST 'https://freshpaint-hipaa-maps.com/v2/reverse-geocode?token=YOUR-ENVIRONMENT-ID-HERE' ``` #### Request body Because we use AWS Location Services, a full account of all supported features, and inputs can be found here: {% embed url="" %} #### Sample CURL request 
# Replace the TOKEN variable with your freshpaint environment ID
# Go to the URL below to see how to find your Freshpaint Environment ID
# https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id
TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE"

curl 'https://freshpaint-hipaa-maps.com/v2/reverse-geocode?token=$TOKEN' \
  -H 'accept: application/json' \
  -d '{"QueryPosition": [-122.3394,47.6159], "MaxResults": 8}'
## Frequently Asked Questions **Can I use Freshpaint maps with React, Angular, or other web frameworks?** Yes. Freshpaint hasn't seen enough interest in any of these to prepare examples, but all that should be needed is to embed maplibre-js and point the library at the Freshpaint tiles as our regular JS demos use. If you need help you can always contact Freshpaint support. **Can I zoom the map to automatically capture all of my locations?** Yes. The maplibre fitBounds call supports providing a list of Longitude and Latitude pairs, and will provide a bounding box that contains all the added pins. When calling fitBounds on the map make sure to add some padding so any pins are not right on the edge of the bounding box. ```javascript bounds = new maplibregl.LngLatBounds(); bounds.extend(m.LngLat); // Add every LngLat to the bounds map.fitBounds(bounds, { padding: 100 }); // Set the padding to how much extra space is needed ``` **Can I use browser based location services to identify the location of the website visitor?** Many browser support a geolocation API which will give you approximate coordinates of the browser if allowed by the user. See the [Geolocation API docs](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) for what most web browsers will provide for accessing web visitor coordinates. **Can I install maplibre into my project instead of using the version from Freshpaint** Yes. The maplibre libraries provided by Freshpaint servers are not modified. **Does the Freshpaint SDK need to be installed on a page for the Maps feature to work?** No, the Maps feature can work independently on your page without depending on the presence of the Freshpaint SDK. You only need the Freshpaint SDK loaded if you wish to track interactions with the map. Otherwise, it can be used as a standalone HIPAA-compliant map plugin. # Maps v0 (deprecated) Freshpaint offers a HIPAA-compliant, Customizable, Zoomable, Panable map and location services APIs that can be embedded within healthcare focussed websites. {% hint style="danger" %} ## This version of Maps has been deprecated. If you're a new adopter of maps, please refer to [Maps](/readme/maps) instead for instructions on how to integrate with the most up to date version of Maps. If you have already integrated and are looking for references, please read on. {% endhint %} ## Introduction Many healthcare organizations utilize maps as part of their web presence to aid in user conversions by understanding where a healthcare provider is located. Freshpaint offers a series of HIPAA safe base components for building Maps components and location services into a web page. ### Map Tiles Map tiles are the data about how to draw a map at a particular location. These tiles contain all the information about the locations of everything to be drawn a map, all the rivers, roadways, labels, buildings, and more. Freshpaint serves tile information based on AWS's Location Services which uses [HERE maps](https://www.here.com/) as its provider. ### Drawing a Map Freshpaint recommends using [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) as the code library to use to draw the maps on a web page. Maplibre-js is a fully featured open-source library that understands the map tiles served by Freshpaint and can render them into a map on a web page. Maplibre also provides similar functionality as other mapping services you may have used or seen elsewhere. If your website is built using a framework, you can use any of the MapLibre libraries or wrappers that are available for the particular framework. Freshpaint provides access to the unmodified MapLibre libraries from the freshpaint-hipaa-maps.com domain if you want a convenient place to access the web libraries for drawing a map. ```html ``` ### Location Services API Some more interactive web experiences require the use of location services APIs. Freshpaint provides access to a number of location services APIs that are used for Geocoding, Reverse Geocoding, and location search. For example, a website developer may want to organize location results by distance from a website visitor. This might be done through requesting a zip code from the user. The location API allows the website to request the coordinates of a zip code, and then knowing the latitude and longitude of both the zip code and locations allows code to be written that will reorganize the results based on distance. Freshpaint provides access to the [Amazon AWS Location Service](https://aws.amazon.com/location/) for providing location APIs to a website visitor. ## Using the Location Services API Freshpaint provides access to the Amazon AWS Location Services by accessing Freshpaint services. So in the amazon location services docs, you might see: `/places/v0/indexes/IndexName/search/suggestions?key=Key` You would instead use ``` https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=YOUR-ENVIRONMENT-ID-HERE ``` See on how to find you're environment ID and replace `YOUR-ENVIRONMENT-ID-HERE` with the token for you're particular Freshpaint environment. {% hint style="info" %} The AWS API Docs indicate the use of an API Key as the ?key=Key parameter on their examples. When using the location services with Freshpaint you instead use ?token=YOUR-ENVIRONMENT-ID-HERE to access the location services from Freshpaint. The key parameter is not used when accessing the location services through freshpaint-hipaa-maps.com {% endhint %} ### Common Functions #### SearchPlaceIndexForSuggestions Generates suggestion results for addresses or point of interest based on partial or misspelled free-form text. This could be used for functionality related to autocomplete, autosuggest, or fuzzy matching. [AWS Docs for SearchPlaceIndexForSuggestions](https://docs.aws.amazon.com/location/previous/APIReference/API_SearchPlaceIndexForSuggestions.html) #### SearchPlaceIndexForText Geocodes free-form text, such as an address, name, city, or region to allow you to search for a place or point of interest. You can apply filters or bounding boxes in the request to only return locations in the correct geography. [AWS Docs for SearchPlaceIndexForText](https://docs.aws.amazon.com/location/previous/APIReference/API_SearchPlaceIndexForText.html) #### SearchPlaceIndexForPosition Sometimes referred to as Reverse Geo-coding, takes a given coordinate and returns a Place and information such as address, country, etc related to the returned Place. [AWS Docs For SearchPlaceIndexForPosition](https://docs.aws.amazon.com/location/previous/APIReference/API_SearchPlaceIndexForPosition.html) #### GetPlace Returns additional information about a place. Other API operations may return a PlaceID, and GetPlace can be used to find the address, categories, countries and more about the PlaceID. [AWS Docs for GetPlace](https://docs.aws.amazon.com/location/previous/APIReference/API_GetPlace.html) ## Examples The example site has a full working demo that you can inspect and customize to your needs. {% embed url="" %} A demo site showing the Freshpaint map connected to clickable location cards. When you click on a location card, the map automatically focuses on the location. When you click on a pin, the location cards automatically scroll to the selected location. {% endembed %} {% hint style="info" %} You can use view-source in your browser to see how the demo was built in pure Javascript and HTML. {% endhint %} ### Map Setup: Vanilla JS Freshpaint uses MapLibre as an open-source renderer to display the map. You will need to load MapLibre and its stylesheet. ```html ``` #### Creating a Map 
// Styles affect how the maps look:
// We currently support the following styles:
//   "standard-light":      colorized, typical map style
//   "standard-dark":       colorized, typical dark map style
//   "visualization-light": grayscale, elegant black and white style
//   "visualization-dark":  grayscale, elegant dark black and white style
const style = "standard-light" 

// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id
const envId = "YOUR-FRESHPAINT-ENVIRONMENT-ID"

const map = new maplibregl.Map({
  container: "map",
  style: `https://freshpaint-hipaa-maps.com/${envId}/${style}/style-descriptor`,

  // longitude and latitude of the map's origin
  // Note: this is backwards compared to google maps
  center: [-87.6800, 41.8500],

  // Zoom levels (rough descriptions):
  // 15 : a close street view
  // 13 : city neighborhoods
  // 11 : entire region (Chicagoland)
  zoom: 13,
});

// This adds a toolbar for zooming an panning:
// + : zoom in
// - : zoom out
// compass for rotating (e.g. north facing up or south facing up)
map.addControl(new maplibregl.NavigationControl(), "top-left");
#### Adding pins with popups 
// Note: LngLat is reversed from google maps which does LatLng.
const markers = [
  {
    "LngLat": [-87.7276, 41.7919],
    "Header": "UI Health",
    "Href": "https://hospital.uillinois.edu/"
  },
  {
    "LngLat": [-87.69738, 41.85505],
    "Header": "Saint Anthony Hospital",
    "Href": "https://sahchicago.org/"
  }
];

// You can customize popups with arbitrary HTML
// Here, we just do a simple header and link to the website
const newPopup = (m) => new maplibregl.Popup({ offset: 25 })
                                      .setHTML(`<div>
                                                    <h3>${m.Header}<\/h3>
                                                    <a href="${m.Href}">${m.Href}<\/a>
                                                <\/div>`)

markers.forEach((m) => {
  const popup = newPopup(m);
  const marker = new maplibregl.Marker({color: "#808080"})
                               .setLngLat(m.LngLat)
                               .setPopup(popup)
                               .addTo(map);
});
#### Full working example See the working demo at for a demo with the Freshpaint map connected to clickable location cards. This demo shows how to add on-click handlers to customize behaviors when users click on Map pins. It also shows how to link external actions to the Map (e.g. so on-click outside of the map cause the map to recenter). ### Location Search Setup: Freshpaint also offers a HIPAA-compliant Location search service that finds location matches to user inputs. We offer a backend that can be used with your autocomplete frontend of choice.

Example location autocomplete.

#### API Details The API is accessible at 
// Replace the environment ID below with your freshpaint environment ID
// Go to the URL below to see how to find your Freshpaint Environment ID
// https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id

POST `https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=YOUR-ENVIRONMENT-ID-HERE`
#### Request body Because we use AWS Location Services, a full account of all supported features, and inputs can be found here: #### Sample CURL request ```bash // Replace the TOKEN variable with your freshpaint environment ID // Go to the URL below to see how to find your Freshpaint Environment ID // https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE" curl -H 'Content-Type: application/json' \ "https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/suggestions?token=$TOKEN" \ -d '{"Text": "Good", "MaxResults": 8, "BiasPosition": [-87.69420, 41.86181], "FilterCountries": ["USA"], "FilterCategories": ["MunicipalityType"]}' ``` ### Reverse Geocoding Setup: Freshpaint also offers a HIPAA-compliant Reverse Geocoding API that allows you to look up an address based on Latitude and Longitude. #### API Details The API is accessible at ``` # Replace the environment ID below with your freshpaint environment ID # Go to the URL below to see how to find your Freshpaint Environment ID # https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id POST 'https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/position?token=YOUR-ENVIRONMENT-ID-HERE' ``` #### Request body Because we use AWS Location Services, a full account of all supported features, and inputs can be found here: #### Sample CURL request ```bash # Replace the TOKEN variable with your freshpaint environment ID # Go to the URL below to see how to find your Freshpaint Environment ID # https://documentation.freshpaint.io/reference/faqs/where-do-i-find-my-environment-id TOKEN="YOUR-FRESHPAINT-ENV-ID-HERE" curl -H 'Content-Type: application/json' \ "https://freshpaint-hipaa-maps.com/places/v0/indexes/freshpaint/search/position?token=$TOKEN" \ -d '{"Position": [-122.3394,47.6159], "MaxResults": 8}' ``` ## Frequently Asked Questions **Can I use Freshpaint maps with React, Angular, or other web frameworks?** Yes. Freshpaint hasn't seen enough interest in any of these to prepare examples, but all that should be needed is to embed maplibre-js and point the library at the Freshpaint tiles as our regular JS demos use. If you need help you can always contact Freshpaint support. **Can I zoom the map to automatically capture all of my locations?** Yes. The maplibre fitBounds call supports providing a list of Longitude and Latitude pairs, and will provide a bounding box that contains all the added pins. When calling fitBounds on the map make sure to add some padding so any pins are not right on the edge of the bounding box. ```javascript bounds = new maplibregl.LngLatBounds(); bounds.extend(m.LngLat); // Add every LngLat to the bounds map.fitBounds(bounds, { padding: 100 }); // Set the padding to how much extra space is needed ``` **Can I use browser based location services to identify the location of the website visitor?** Many browser support a geolocation API which will give you approximate coordinates of the browser if allowed by the user. See the [Geolocation API docs](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) for what most web browsers will provide for accessing web visitor coordinates. **Can I install maplibre into my project instead of using the version from Freshpaint** Yes. The maplibre libraries provided by Freshpaint servers are not modified. # Translations Freshpaint offers a HIPAA-compliant translation widget giving customers access to 74 supported languages. ### Live Demo The example site has a full working translation demo. {% embed url="" %} In this demo you can see the translation widget on the bottom left of the page {% endembed %} ### How To Install To install the Freshpaint Translation snippet on your site you need to have three pieces of information 1. Your environment ID ([Where do I find my Environment ID?](/reference/faqs/where-do-i-find-my-environment-id)) 2. What languages does your site want to support (see our [list](#supported-languages) for our supported languages and their language codes). 3. What UI handler would you like to use and the appropriate handler settings (See specific [handler instructions](#snippets)) Once you have the above information you can edit your snippet and paste it into your website source code. ### Snippets We currently have three UI styles clients can choose from. Once you choose the one you like, follow the instructions on how to edit it to get all the appropriate information in the snippet and placed on your site. #### Floating UI This format is a simple UI element that floats on top of the page on either the lower left or the right side of the page. This element is the easiest to install because it doesn't require any existing HTML on the page to inject itself.

UI elements are subject to modification based on your site's CSS.

To edit this snippet follow these instructions: 1. Replace `ENV_ID_HERE` with your [Environment ID](/reference/faqs/where-do-i-find-my-environment-id). 2. Decide if you want the floating UI on the left or right. This snippet is set to left but the word `left` can be replaced with `right`. 3. Languages 1. Decide what languages you want, you do not need to include English (In our example we will use Mexican Spanish, Russian, and Dutch) 2. Find your language codes (In our example we have `es-MX`, `ru`, and `nl`) 3. Format your languages as comma separated strings (`"es-MX", "ru", "nl"`) 4. Replace `LANGUAGES_HERE` with your list 4. Paste this customized snippet onto your site. {% code overflow="wrap" %} ```html ``` {% endcode %} #### Inline Window UI This format is takes up less space but is a little more complex to install since the website needs a destination of where it needs to be inserted.

UI elements are subject to modification based on your site's CSS.

To edit this snippet follow these instructions: 1. Replace `ENV_ID_HERE` with your [Environment ID](/reference/faqs/where-do-i-find-my-environment-id). 2. Insert an HTML div on your website with the ID `fp_translate`. If you need to use a different ID replace `fp_translate` in the snippet with the appropriate div ID. 1. `
` 3. Languages 1. Decide what languages you want, you do not need to include English (In our example we will use Mexican Spanish, Russian, and Dutch) 2. Find your language codes (In our example we have `es-MX`, `ru`, and `nl`) 3. Format your languages as comma separated strings (`"es-MX", "ru", "nl"`) 4. Replace `LANGUAGES_HERE` with your list 4. Paste this customized snippet onto your site. {% code overflow="wrap" %} ```html ``` {% endcode %} #### Basic UI This format is our most basic UI. This element is meant for customers who need very little out of the box functionality and want to completely customize their experience.

UI elements are subject to modification based on your site's CSS.

To edit this snippet follow these instructions: 1. Replace `ENV_ID_HERE` with your [Environment ID](/reference/faqs/where-do-i-find-my-environment-id). 2. Insert an HTML div on your website with the ID `fp_translate`. If you need to use a different ID replace `fp_translate` in the snippet with the appropriate div ID. 1. `
` 3. Languages 1. Decide what languages you want, you do not need to include English (In our example we will use Mexican Spanish, Russian, and Dutch) 2. Find your language codes (In our example we have `es-MX`, `ru`, and `nl`) 3. Format your languages as comma separated strings (`"es-MX", "ru", "nl"`) 4. Replace `LANGUAGES_HERE` with your list 4. Paste this customized snippet onto your site. {% code overflow="wrap" %} ```html ``` {% endcode %} ### Supported Languages | Language Code | Language Name | | ------------- | --------------------- | | af | Afrikaans | | sq | Albanian | | am | Amharic | | ar | Arabic | | hy | Armenian | | az | Azerbaijani | | bn | Bengali | | bs | Bosnian | | bg | Bulgarian | | ca | Catalan | | zh | Chinese (Simplified) | | zh-TW | Chinese (Traditional) | | hr | Croatian | | cs | Czech | | da | Danish | | fa-AF | Dari | | nl | Dutch | | en | English | | et | Estonian | | fa | Farsi (Persian) | | tl | Filipino, Tagalog | | fi | Finnish | | fr | French | | fr-CA | French (Canada) | | ka | Georgian | | de | German | | el | Greek | | gu | Gujarati | | ht | Haitian Creole | | ha | Hausa | | he | Hebrew | | hi | Hindi | | hu | Hungarian | | is | Icelandic | | id | Indonesian | | ga | Irish | | it | Italian | | ja | Japanese | | kn | Kannada | | kk | Kazakh | | ko | Korean | | lv | Latvian | | lt | Lithuanian | | mk | Macedonian | | ms | Malay | | ml | Malayalam | | mt | Maltese | | mr | Marathi | | mn | Mongolian | | no | Norwegian (Bokmål) | | ps | Pashto | | pl | Polish | | pt | Portuguese (Brazil) | | pt-PT | Portuguese (Portugal) | | pa | Punjabi | | ro | Romanian | | ru | Russian | | sr | Serbian | | si | Sinhala | | sk | Slovak | | sl | Slovenian | | so | Somali | | es | Spanish | | es-MX | Spanish (Mexico) | | sw | Swahili | | sv | Swedish | | ta | Tamil | | te | Telugu | | th | Thai | | tr | Turkish | | uk | Ukrainian | | ur | Urdu | | uz | Uzbek | | vi | Vietnamese | | cy | Welsh | # Bot Blocking Freshpaint classifies incoming traffic and blocks bot-generated events from reaching destinations. When bot blocking is enabled, Freshpaint automatically classifies each incoming event and prevents bot traffic from being delivered to destinations or counting towards MTUs. Bot blocking is not enabled by default. ## 1. Functionality Freshpaint applies a `$source_classification` property to every event at ingestion. This property indicates whether the event originated from a known bot or from regular traffic. It is present on all events regardless of whether bot blocking is enabled for the account.
ClassificationDescription
UNCLASSIFIEDTraffic that does not match any known bot pattern. This typically represents normal user activity.
KNOWN_BOTTraffic that matches known user agents for web crawlers such as Googlebot, Applebot, Bingbot, and others.
AWS_BOTTraffic that matches a specific bot pattern observed on AWS infrastructure, identified by a combination of browser characteristics and source IP address.
When bot blocking is not enabled, all events, including those classified as bots, are delivered to destinations normally. When bot blocking is active on an account: * Events with a `$source_classification` of `KNOWN_BOT` or `AWS_BOT` are **not delivered** to any destination. * Blocked bot events do **not count** towards MTU usage. * Blocked events still appear in [Traces](/admin-panel/investigate-testing-and-debugging/traces) with a **Bot Detected** status for debugging purposes. ### Viewing Source Classifications In [Traces](/admin-panel/investigate-testing-and-debugging/traces), events classified as bots display a **Bot Detected** status. Use the status filter to isolate these events.
"Event Verification" library with "bot detected" status checked. Shows traces with status "bot detected".
## 3. Enable Bot Blocking To request bot blocking, contact a Freshpaint representative or email ****. # Web Tracker Monitoring Freshpaint gives you visibility into the trackers installed across your website, so you can more quickly make the decisions that keep you HIPAA-compliant. ## What Is A Web Tracker? Services such as Google Analytics and Facebook Advertising ask their clients to install software on their websites. You may have added the Google Tag or the Facebook Pixel to your site - those are both examples of Web Trackers. For HIPAA-covered entities, Web Trackers can pose a big risk to the extent that they facilitate sharing PHI from your site with unauthorized third parties. ## Get Notified About New Trackers Freshpaint delivers a weekly report to your inbox with information about new trackers installed. To set up your weekly reports, read our [getting started guide](#how-to-get-started). ## See Where Trackers Are Installed Freshpaint’s weekly report shows you installed trackers and provides you a complete list of the pages they’re installed on so you can better assess whether they could be sharing PHI. ## Get Context About Trackers Freshpaint provides context about the highest risk trackers identified to help you know where to start your audit. ## Take Next Steps to Mitigate HIPAA Risk Freshpaint guides you towards HIPAA compliance by presenting different options to resolve each tracker found on your site. The [next page](/readme/web-tracker-monitoring/tracker-resolution-types) describes the different resolution types and how to proceed with them. ## Organize Your BAAs Upload your BAA for each tool on your site. You won't need to wonder whether your organization has a BAA in place, and you won't have to search to find the document. ## How It Works Freshpaint scans your entire site by starting from the home page and following links to explore from there. We will explore all pages on the site including subdomains. For example, we would follow a link from example.com to my.example.com. {% hint style="info" %} Freshpaint is not able to monitor web trackers on the portions of websites that require the user to log in, such as a patient portal. {% endhint %} For each page, we keep track of which third party tools may be collecting PHI. We'll send you an initial report of all of the trackers we find on your site. Each week, we'll re-scan your site and notify you of any new trackers that have been added. {% hint style="info" %} It may take up to one week to generate the initial Web Tracker Report for your site {% endhint %} ## How To Use Your Report ### Tracker Overview The first tab provides you a list of the trackers we were able to identify. We provide context and descriptions where we can (this will get better over time) about each tracker and assign a level of HIPAA compliance risk.
### Pages Per Tracker The additional tabs show you all the pages each tracker is installed on.
### Risk Levels **Highest:** Shares PHI, does not offer BAAs, and Freshpaint offers a HIPAA-compliant replacement **High:** Shares PHI and does not offer BAAs or might not offer BAAs **Medium:** Shares PHI but supports signing BAAs **Low:** Does not share PHI, or you need to sign a BAA to work with them **Unknown:** Freshpaint has not assessed the risk of this tracker ### Next Steps Once you have your report, read our [Privacy-First Framework](https://www.freshpaint.io/blog/privacy-first-framework-for-hipaa-compliance?87a81329_page=1) for best practices on keeping your site HIPAA-compliant. [Visit the next page](/readme/web-tracker-monitoring/tracker-resolution-types) to learn more about the different options to mitigate a tracker's risk, and then login to the Freshpaint UI to mark trackers as resolved for various reasons. ## Web Tracker Manager You can also view the latest Web Tracker Report for your site in the Freshpaint app by navigating to "Monitoring" -> "Web Trackers" in the left sidebar.

Navigating to the Web Tracker Manager

You can view the full list of trackers installed on your site, along with their respective risk levels. You can also click to view a detailed page for each tracker. On a tracker's detailed page, you can choose [different options to mark a tracker as resolved](/readme/web-tracker-monitoring/tracker-resolution-types); you can also add arbitrary notes about a tracker, or upload a BAA if you already have a signed BAA with the provider.
### Configuring Your Scan Click the "Settings" icon in the Web Tracker Manager lets you customize your scan. You can use this to exclude certain pages from the scan. For example you might want to exclude the "careers" portion of your site since that would not risk exposing the user's health information. Specify a list of patterns. If any of these patterns are found in a URL, Tracker Monitoring will skip that page. For example, excluding "/careers" will skip all pages containing that path such as , .

Configuring pages to exclude for your site

## How To Get Started Freshpaint customers can set up Web Tracker Monitoring by contacting . Please provide the following information: 1. The URL to the home page of the site that you need to monitor 2. The email address(es) where Freshpaint can send the reports. Admins can update the list of email addresses as needed. It may take up to one week to generate the initial report for your site. ### Allow Freshpaint's IP Address Your site may have a firewall to prevent bots. We recommend contacting your organization's IT team and asking them to ensure that Freshpaint is able to scan your site. You can send them the following message: > Freshpaint is working with your marketing and compliance teams to help with your organization's HIPAA compliance. We are setting up web tracker monitoring for your site, and we want to make sure we will not be blocked or rate-limited by your bot detection / firewall. > > Could you please allowlist Freshpaint's IP address 35.162.70.108 so that we are able to scan the site? > > For context, we plan to crawl the entire site, including subdomains, about once per week. There may be additional crawls occasionally, particularly while we're first setting up the monitoring. > > Please feel free to reach out to with any questions. # Tracker Resolution Types
The Web Tracker Monitoring UI allows you to choose different options to mark a tracker as resolved. This document describes your options for mitigating the risk presented by having a Web Tracker installed on your site. Once you choose and submit and a resolution status, we'll let you know if there are any next steps you should take to resolve the tracker. These next steps will appear in the "Action Items" section underneath the Resolution Picker. When you complete these action items, Freshpaint will automatically adjust the tracker's risk level to "Low Risk" accordingly. {% hint style="info" %} All trackers will continue to be scanned and will show up in your weekly report, regardless of whether they have been "resolved" or not. Our aim is to show you the full view of which trackers still need your attention and which you've already resolved. {% endhint %} ## Resolution 1: Signed BAA Many vendors will sign a Business Associate Agreement with you. If you are able to set up a BAA with the vendor, then their trackers no longer present a HIPAA risk on your site. Choosing this resolution will move the tracker to a “low risk” status, allowing you to focus on any remaining high risk items.

After choosing "Signed BAA" status, the action item is to "Upload document" if you haven't already

## Resolution 2: Mark as Safe If you decide to allow the tracker to remain on your site, you can select “Mark as Safe” in Freshpaint’s Web Tracker Manager. Choosing "Mark as Safe" will immediately move the tracker to a “low risk” status, so you can focus your attention on any remaining high risk items. {% hint style="info" %} If a tracker is installed only on the Job Postings page and the About Us page, you may decide along with your compliance and legal teams that there is little risk of HIPAA violation. Freshpaint’s Web Tracker Report shows you which pages on your site have the tracker installed, and which ones do not. {% endhint %} ## Resolution 3: Remove Tracker You may need to completely uninstall the tracker from your site. The removal process depends on how the tracker is installed: * If the tracker is set up via a tag manager such as Google Tag Manager, locate the tracker in the tag manager and remove it. * Otherwise, your IT team will need to remove the tracker. You can send them the Freshpaint Web Tracker Report along with the following note: > Please remove the tracker \ from our organization’s website(s). I’ve attached a report listing all of the pages that the tracker is installed on, which should help you find the tracker and make sure that it is completely removed from every page. This task is critical for maintaining our organization’s HIPAA compliance. ## Resolution 4: Replace with Freshpaint Freshpaint integrates with advertising platforms, analytics tools and other services. If you replace the third party tracking technology with Freshpaint, you can continue using your tools while maintaining HIPAA compliance. {% hint style="info" %} If Google Analytics is found on your site, you can replace it with Freshpaint’s Google Analytics 4 Proxy integration. {% endhint %} ## Resolution 5: Owned By My Organization Your site may be retrieving resources from or sending information to additional first-party domains. There is no risk of violating HIPAA if PHI is shared with these domains since they are owned by your organization. Choosing this resolution will immediately move the tracker to a “low risk” status. {% hint style="info" %} If your organization’s homepage is [freshhealth.co](http://freshhealth.co), there may be trackers on your site such as [myfreshhealth.co](http://myfreshhealth.co) or [freshhealth-schedule.co](http://freshhealth-schedule.co). These domains belong to your organization, so there is no risk of violating HIPAA if PHI is shared with them. {% endhint %} # Historical Scans
Visit the [Historical Scans](https://app.freshpaint.io/monitoring/history) page to view your efforts towards HIPAA compliance over time and retrieve past Web Tracker Monitoring reports. These insights can be shared with your compliance and leadership teams to demonstrate progress toward compliance.
### Understanding the Chart The Trackers By Risk Level chart is broken down into 5 categories that are labeled along the vertical axis: Unknown, Low, Medium, High, and Critical. These are the same categories you'd see in your weekly Web Tracker Monitoring report. Time runs along the horizontal axis. For each week, you can see the number of trackers categorized by risk level by hovering over the individual bars. To see the number of trackers detected for each category and week, toggle the "View labels" setting.
### Extending Chart Date Range Use the range selector to view further back in time, all the way up to the first time web tracker monitoring was set up for your website.
### Downloading Reports For further analysis, select the tabular view. You'll be able to download each weekly report in XLSX format to see the full list of trackers found each week.
# Custom Domains First-party tracking through your own domain. Custom domains route the Freshpaint Web SDK and all tracking endpoints through a subdomain you own. Browsers treat requests to your domain as first-party traffic, which ad blockers and privacy tools are far less likely to block. The result is more accurate data collection and a cleaner network footprint for your site. This page helps you: * Understand why custom domains improve data accuracy * Know what to prepare before setup begins * Follow along during the setup process with your Freshpaint team * Update your Freshpaint snippet once setup is complete ### 1. Why Custom Domains Matter #### 1.1 Ad Blocker Resilience Ad blockers maintain lists of known third-party tracking domains. When Freshpaint loads from its default domains, some browsers block those requests entirely — meaning you lose visibility into that user's behavior. A custom domain routes all Freshpaint traffic through a hostname you own, so browsers treat it as first-party and ad blockers typically allow it through. {% hint style="info" %} #### Related: For background on how ad blockers affect analytics, see [How do I circumvent ad blockers?](/reference/faqs/how-do-i-circumvent-ad-blockers) {% endhint %} #### 1.2 Brand Consistency Network requests from your site point to your own hostname rather than a third-party domain. This provides a cleaner experience if your users or engineering team inspect network traffic. #### 1.3 Single Hostname Custom domains consolidate all Freshpaint services — the SDK, tracking API, event definitions, and impression beacon — behind one hostname. No need to manage multiple endpoints. ### 2. Prerequisites Before reaching out to Freshpaint, confirm the following: * A domain you control — You need DNS access to the domain where you want to create a subdomain (for example, if your site is `yoursite.com`, you might use `data.yoursite.com`). * Someone who can add DNS records — You will need to add two CNAME records during setup. Confirm you can make DNS changes or coordinate with your IT team ahead of time. * A subdomain name that avoids blocked keywords — See guidance below. {% hint style="warning" %} Choose your subdomain carefully. Ad blockers scan hostnames for common tracking-related words. Avoid `track`, `tracking`, `analytics`, `pixel`, `beacon`, `collect`, and `telemetry`. Choose something neutral like `data.yoursite.com`, `edge.yoursite.com`, or `cdn.yoursite.com`.
{% endhint %} ### 3. Setup Process Custom domain setup is handled by the Freshpaint team — there is no self-serve configuration. Your customer success team or support will walk you through each step. Here is what to expect. #### 3.1 Request Setup Contact your Freshpaint CSE or email with: * Your account information * The custom subdomain you want to use (for example, `data.yoursite.com`) #### 3.2 Freshpaint Provisions Your Infrastructure The Freshpaint team creates the infrastructure to serve all Freshpaint services through your domain. This step is handled entirely on our side. #### 3.3 Configure DNS Records Freshpaint provides you with two DNS records to add in your DNS provider. The Freshpaint team will walk you through this step and verify the records are configured correctly. 1. Certificate validation record — proves domain ownership so a TLS certificate can be issued for your subdomain. Certificate validation typically takes a few minutes but can take up to a few hours. 2. Domain routing record — points your subdomain to the Freshpaint infrastructure. This is added after the certificate is issued. #### 3.4 Freshpaint Verifies and Activates Once both DNS records are in place, the Freshpaint team verifies that your custom domain is resolving correctly and all Freshpaint endpoints are reachable. Freshpaint confirms your domain is active and ready to use. #### 3.5 Update Your Freshpaint Snippet Update the Freshpaint snippet on your site to include the `custom_domain` parameter. You can find your updated snippet in the Freshpaint dashboard under your environment's setup instructions after setup is complete. The Freshpaint team will flag when this is ready for you! {% hint style="success" %} No data loss during migration. Events continue flowing through Freshpaint's default endpoints until the updated snippet is deployed. Once live, traffic seamlessly shifts to your custom domain. {% endhint %} ### 4. Content Security Policy (CSP) If your site uses a Content Security Policy header, you must add your new subdomain to the `connect-src` and `script-src` directives. Otherwise, browsers will block requests to your custom domain even though DNS and infrastructure are working correctly. Coordinate with your engineering team if you are unsure whether your site uses CSP. ### 5. Migrating from Legacy Ad Block Bypass If you are already using the Ad Block Bypass feature described in [How do I circumvent ad blockers?](vscode-file://vscode-app/Applications/Cursor.app/Contents/Resources/app/out/vs/code/electron-sandbox/workbench/link), custom domains are the recommended upgrade. Custom domains consolidate all Freshpaint services behind a single hostname you own, replacing the previous multi-endpoint approach. To migrate, contact your CSE or . The Freshpaint team handles the transition — you only need to update your snippet once the new domain is ready. ### Best Practices & Reminders * Pick a neutral subdomain name Avoid terms that ad blockers target — `track`, `analytics`, `pixel`, `beacon`, `collect`, or `telemetry`. A generic name like `data`, `edge`, or `cdn` works well. * Update the snippet promptly after setup * Your custom domain is only effective once the updated snippet with the `custom_domain` parameter is deployed. Until then, requests continue through default Freshpaint domains. * Coordinate with your IT and engineering teams early DNS changes and snippet updates may involve different teams. Loop everyone in at the start so the process goes smoothly. * Keep your DNS records in place Removing the CNAME records for your custom domain or the certificate validation will break the integration. Treat these DNS records as permanent. * Check your Content Security Policy If your site enforces CSP headers, the new subdomain must be allowed in `connect-src` and `script-src`. ### What's Next? * Request setup — Email or contact your CSE with your account name, preferred subdomain, and DNS access confirmation. * Verify data flow — Once the snippet is live, check your Freshpaint dashboard to confirm events are arriving through your custom domain. # Short Links and QR Codes ## Overview Freshpaint's Short Links feature creates shortened URLs and associated QR codes within the BAA-covered Freshpaint environment, helping your organization share clean, concise links without routing potentially sensitive information through third-party services without dedicated BAAs.
Freshpaint Short Links List in Freshpaint Account
### Why URL Shortening Matters for Healthcare URLs used in patient communications frequently contain information that may constitute PHI under HIPAA, including patient identifiers in query parameters, appointment IDs, portal session tokens, care program codes, and provider or clinic location parameters. If any of those URLs pass through a third-party shortener without a BAA, that transmission may represent an unauthorized disclosure of health information. Most commodity URL shorteners do not sign BAAs and log the full content of URLs that pass through their infrastructure. This creates compliance exposure that often goes undetected until a security audit surfaces it. Freshpaint Short Links operates entirely within the Freshpaint platform, the same BAA-covered environment that already handles your data. No additional vendor relationships, contracts, or security reviews are required. If you have an existing BAA with Freshpaint, you're already covered. ### Common Use Cases **Appointment reminders:** Appointment confirmation and reminder messages often include individualized portal links with patient-specific parameters. Short links let you include clean, concise URLs in SMS and email without shortening PHI-bearing URLs through a non-BAA service. **Patient portal links:** Portal links scoped to a specific patient session can be shortened for use in outreach campaigns, care coordination messages, or discharge communications. **Marketing campaigns:** Campaign URLs with UTM parameters, care program identifiers, or clinic-specific routing parameters can be shortened without moving that data outside your BAA boundary. **Care operations:** Teams sending high volumes of individualized links, such as scheduling links, intake forms, or post-visit surveys, can generate short links for use at scale. ### How it Works When you create a short link in Freshpaint, the platform generates a unique code and maps it to your destination URL. That mapping is stored within Freshpaint's secure infrastructure. When a visitor on the site clicks the short link, they are redirected to the original destination, and the redirect transaction is logged within the same protected environment. Short links use randomly generated codes rather than encoding information from the original URL, which means the short link itself does not expose PHI even if the destination URL contains it. All URL storage, redirect logging, and access controls are subject to your BAA with Freshpaint and align with Freshpaint's existing data retention policy. ## Create Short Links In your Freshpaint account, navigate to "Short Links". Click "Create Short Link".
Create Short Link dialog box in Freshpaint account
The "Create Short Link" dialog will appear.
Create Short Link dialog open in Freshpaint Account
1. Paste or type the full destination URL into the Destination URL field. This is the URL that visitors will be redirected to when they click the short link. 2. Give the short link a `Title` so you can see in the overview table what it entailed, for example “Mother’s Day Cancer Screenings” or “Flu shot campaign” – whatever keywords or details will make it easy to track your short links. 3. Select a domain to use for your short links. The default is a Freshpaint domain, but soon you will be able to introduce your own custom domains. 4. Determine how long you want to make your short links. Six characters are more visually pleasing, especially for SMS. You get more possible variations with eight characters. 5. If you want to track multiple links across topics or campaigns, use Tags to do so. For example, if you create many Flu-related links throughout the year, using a Flu tag will let you see how all Flu-related links perform over time from the Metrics overview. 6. Click Create to generate the short link. Once created, your short link is ready to use. Copy it and paste it into email campaigns, SMS messages, or any patient-facing communication channel. ### View QR Codes
Freshpaint Short Links List with expanded menu and 'Preview QR Code' selected
Once a short link is live, so is the corresponding QR code. Locate it within the menu on the far-right of the webpage. Select "Preview QR Code" to see and test the QR code or download it to use in marketing materials. ### Manage Available Short Links #### Viewing Available Short Links The [Short Links Overview page](https://app.freshpaint.io/short-links/overview) displays all links created in your account, including: * The short link URL * The destination URL * Title * Tags * Creation date * Total click count #### Disable or Edit Short Links Freshpaint makes it possible to edit and disable short links that you no longer need or want live online. To do so, locate the menu on the far-right of the webpage. Select Disable or Edit to make changes to the short link.
Freshpaint Short Links List with expanded menu and 'disable' selected
#### Access Controls and Audit Trails Freshpaint maintains records of who created each short link and when. Access to the original destination URL is controlled and is not publicly exposed. If your compliance or security team needs documentation on data flows for a review, contact your Freshpaint Account Manager to request the relevant materials. ### Monitor Link Performance #### View Click Metrics Select any short link from the Short Links page to view its performance metrics. Available data includes total clicks over time, giving you a view into how your links are performing across campaigns and patient communications. {% hint style="info" %} Analytics capabilities are actively expanding. If your team needs additional metrics, such as click-through by channel, device type, or referrer, share that feedback with your account manager. Early input is shaping the analytics roadmap. {% endhint %} ### Best practices and Reminders * **Use short links wherever PHI may appear in URLs.** If you're unsure whether a URL contains PHI, treat it as if it does. Patient identifiers, appointment details, and portal parameters are common sources of PHI in URLs that teams often overlook. * **Do not use third-party shorteners for PHI-bearing URLs.** Using Freshpaint's URL Shortener for patient-facing links while continuing to route some URLs through non-BAA tools creates inconsistent compliance coverage. Audit your existing workflows to identify any remaining exposure. * S**hare feedback on what's missing.** The URL Shortener is expanding. If you need custom domains, expiration controls, bulk link creation, or deeper analytics, reach out to your account manager. Your requirements are actively informing the roadmap. # Destinations Destinations are the tools to which you send data from Freshpaint. When you send data from Freshpaint to a destination, Freshpaint will automatically make the right API calls to get the data from Freshpaint into the destination. That way, you only have to think about getting data into Freshpaint and Freshpaint will take the rest from there. ## Types of Destinations ### Demand Side Platforms (DSPs) A Demand Side Platform (DSP) is a software system that allows advertisers to buy digital ad space automatically across multiple platforms. {% content-ref url="/pages/Z2a3hpwYw9BJWLBHqMdR" %} [Demand Side Platforms (DSPs)](/integrations/destinations/demand-side-platforms-dsps) {% endcontent-ref %} ### Direct Response Ads Direct Response Ads destinations let you send data to various advertising platforms to target ads to your users. See the Direct Response Ads destinations docs for more information. {% content-ref url="/pages/JFuP1VYMgxVmMOb4W1Nz" %} [Direct Response Ads](/integrations/destinations/direct-response-ads) {% endcontent-ref %} ### Data Activation Data Activation destinations are the most common type of destination. A Data Activation destination is a third party tool that processes your Freshpaint data in some way. Analytics tools, session replay tools, and email marketing tools are all Data Activation destinations. Check out the Data Activation destinations docs for more information on the specifics of app destinations. {% content-ref url="/pages/Fzx3yxbFIwDEnCuxNiIX" %} [Data Activation](/integrations/destinations/apps) {% endcontent-ref %} ### Data Warehouses Warehouse destinations are data warehouses that give you direct access to your Freshpaint data. After configuring a warehouse destination, you can run SQL over the data and process it however you want. Checkout the warehouse destinations docs for more information on them. {% content-ref url="/pages/-MB1ErvR-UG7gQ0ulm27" %} [Data Warehouses](/integrations/destinations/warehouses) {% endcontent-ref %} ### Functions Functions destinations allow you define custom Javascript application code that is executed when an event fires. {% content-ref url="/pages/DRZiqBdg4bkMKJ7DuEXR" %} [Functions](/integrations/destinations/functions) {% endcontent-ref %} ### Consent Management Consent managers give your users the ability to choose what data is collected about them when using your app and for what purposes that data is used for. {% content-ref url="/pages/WRME4AspeXe9QMyju3td" %} [Consent Management](/integrations/consent-management) {% endcontent-ref %} ## Transforming Data You can modify events before they are sent to destinations by using our transformations. {% content-ref url="/pages/-MK\_985zz3ru4S2ihmYh" %} [Transformations](/admin-panel/transformations) {% endcontent-ref %} # Demand Side Platforms (DSPs) A Demand Side Platform (DSP) is a software system that allows advertisers to buy digital ad space automatically across multiple platforms. It uses real-time bidding to target specific audiences and optimize ad delivery for better performance. DSPs help streamline ad buying, improve ROI, and centralize campaign management in one platform. # Basis Send advertising events directly to Basis Technologies {% content-ref url="/pages/bnJciLNLqu8UWdJLBPKQ" %} [Basis Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/basis/basis-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/MHh4HLiDhodxCEsXEXD8" %} [Basis Reference](/integrations/destinations/demand-side-platforms-dsps/basis/basis-reference) {% endcontent-ref %} # Basis Quick Start Guide Send advertising events directly to Basis Technologies This is a guide to help you get started on sending your conversion events to Basis via Freshpaint. If you've already completed set up and are looking for more information, see [Basis Reference](/integrations/destinations/demand-side-platforms-dsps/basis/basis-reference). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Basis** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Basis::123456.** You can retrieve this value from Basis configuration page for the Pixel ID of interest. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What you'll need 1. Your Universal Pixel ID from Basis 1. Select the appropriate Brand 2. Navigate to the Universal Pixel screen 3. Either create a new pixel, or if one already exists, click on Action > Get Tags 4. Ensure that the `Enable cookieless conversion` checkbox is checked. 5. Copy your Universal Pixel ID from the line `cntrUpTag.track('cntrData', '');` 2. Universal ID configured in Freshpaint 3. \[If in HIPAA mode] Allowlist setup to forward the `$cntr_auctionId` prop to Basis 4. Freshpaint[ Impression Pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)enabled 5. Conversion tracking enabled in Basis 1. Add (or identify an existing) relevant conversion under the appropriate Brand in Basis 2. Ensure this conversion is added to the appropriate Universal Pixel as a rule set in Basis 3. On the campaign, ensure conversion tracking is set to ON and the conversion is being Tracked 6. Freshpaint[ Impression Pixel](https://documentation.freshpaint.io/integrations/impression-pixel) URL added to your creatives in Basis ### To set up Basis with Freshpaint, follow these steps: 1. Make sure you have the appropriate access in both Freshpaint and Basis: 1. Contact your Freshpaint Account Manager to request access to this destination. Once you have that, we will help you step by step through the configuration process 2. Set up your Universal Pixel, and copy your Universal Pixel ID

Select your Brand

Get Tags for the relevant Universal Pixel associated to the Brand

Ensure cookieless conversion is enabled, and copy your Universal Pixel ID

3. Configure the Universal Pixel ID you copied in step 1 in Freshpaint

Set your Universal Pixel ID in Freshpaint

4. Allowlist the `$cntr_auctionId` property. This property is required to support conversion reporting to Basis.

Basis Allowlist set up in Freshpaint

5. Enable the [Freshpaint Impression Pixel](https://documentation.freshpaint.io/integrations/impression-pixel). This enables Freshpaint to do view through attribution within Freshpaint and report the conversion event to Basis. We recommend enabling both IP matching and Cookie matching, and setting the Conversion Window to 30 days for the best results. Then copy the `Pixel Configuration URL` for step 8. Click `Save` once you have set your preferred configuration options and copied the url.

Impression Pixel set up in Freshpaint

{% hint style="info" %} Configuring the impression pixel does not require sharing an IP address or Cookie with Basis. Freshpaint will do the attribution by matching either the IP address or Cookie to an impression that is seen by the Freshpaint Impression Pixel, and if a match is found, will send the impression id to Basis. {% endhint %} 6. Enable Conversion Tracking in Basis

Create or validate conversion in Basis

Add Conversion to the Universal Pixel as a rule set

Enable Track Conversions for Campaign in Basis

7. Add Freshpaint Impression Pixel URL to your ads. **This is required for view through conversion tracking via Freshpaint.** The URL that you paste in should look like `https://freshpaint-impression.com/pixel.png?env_id=&dest_id=&cke=1&$cntr_auctionId={auctionId}`

Set Impression Pixel URL on the relevant ads in Basis

### To send an event to Basis, you'll need to enable the destination for the event: If you'd like to send an autotrack event from your event library to Basis, navigate to your Freshpaint event definition and toggle the destination on to enable the event to be sent to Basis. If you've configured multiple Pixel IDs, you'll need to toggle each pixel individually for each Freshpaint event. If you're using Google Tag Manager to send data to Basis, you'd simply create a tag with the Freshpaint tag template in Google Tag Manager and select the tag type "Basis". If you have multiple Pixel IDs enabled for Basis, you'll need to specify which ID(s) you'd like to enable the event for in the event tag. ### Set up a test campaign in Basis 1. Set up a test campaign that targets a small audiences and set a low budget ($10-50) 2. Attach a creative that has the Frespaint Impression Pixel 3. Verify impressions and clicks are flowing into Freshpaint correctly by working with your Customer Success Engineer 4. Verify in Freshpaint that the events triggering and flowing through to successfully to Basis by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging) ### Confirm and Validate Conversions in Basis Congratulations! Once you have confirmed conversions in Basis, you have finished setting up this integration. Looking for more information? See [Basis Reference](/integrations/destinations/demand-side-platforms-dsps/basis/basis-reference) # Basis Reference Send advertising events directly to Basis Technologies This is a reference document for the Basis destination. For information on how to set up this integration, see the [Basis Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/basis/basis-quick-start-guide) ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Basis** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Basis::123456.** You can retrieve this value from Basis configuration page for the Pixel ID of interest. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Click Through Tracking In order for Freshpaint to be able to automatically capture the click ID auto-generated by the Basis advertisement, [cookieless conversion attribution needs to be enabled](https://help.basis.com/docs/Cookieless_Conversions/Cookieless_Conversions_Guide.htm). Basis will append a `cntr_auctionId` parameter to the landing page URL query string, which works similar to click id's from other advertising platforms. Freshpaint when installed on a page will look for this click id and automatically set the `$cntr_auctionId` event property with the click id. Assuming you have followed the [Basis Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/basis/basis-quick-start-guide) to set up your Basis destination, you can verify that click through tracking is working by looking for an event in event verification that contains the `$cntr_auctionId` field.

Event Verification

Click ID being captured

## View Through Tracking Freshpaint supports view through tracking by capturing the `cntr_auctionId` passed in by Basis using the Freshpaint Impression Pixel. Assuming you have followed the [Basis Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/basis/basis-quick-start-guide) to set up your Basis destination, you can verify that view through tracking is working by looking for an event in event verification that contains the `$cntr_auctionId` field, similar to how you can verify Click Through Conversion. You can also look for a transformation that shows that the event data was enriched by the Freshpaint Impression Pixel.

Transformation applying the Impression Pixel captured impression to an event

## Relevant Properties
Freshpaint PropertyBasis ParameterTypeRequired?Description
$cntr_auctionIdcntr_postbackAuctionIdstringRequiredcntr_auctionId is appended to the landing page URL by Basis. Freshpaint will automatically capture cntr_auctionId for events from your website. For events from other sources you would need to provide $cntr_auctionId as an event property.

If the Freshpaint Impression pixel is in use, cntr_auctionId is added automatically as a transformation to the appropriate events if a match is found.
<custom_property><custom_property>stringOptionalAny additional / custom properties on the event and allowed by the HIPAA allow list will be passed to Basis
# Google Campaign Manager 360 ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Google Campaign Manager 360 Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started Freshpaint's Campaign Manager 360 (CM360) conversions destination allows for tracking click- and view-through conversions from ads managed in CM360, including those linked with other Google Marketing Platform products like Display and Video 360 (DV360). The integration is used to send conversion data to Floodlight Activities within CM360. ### Connecting Campaign Manager 360 to Freshpaint To proceed with setup, you will need the following: * A CM360 account that is [enabled for API access](https://developers.google.com/doubleclick-advertisers/getting_started) (this is the case by default for most CM360 accounts) * A user profile in your CM360 account that has access to the advertiser and Floodlight activities you would like to connect and the "Insert offline conversions" permission * A Freshpaint account that has the CM360 Conversions API destination enabled When adding a new CM360 destination to Freshpaint, you will need to specify a profile ID and advertiser ID

Configuration for a CM360 destination in Freshpaint.

Profile ID is a seven digit number associated with the account you are going to connect to CM360. Note that for the CM360 integration to work, the profile ID here *must* belong to the account that is connected via OAuth.

User profiles screen in Campaign Manager 360. In this example, the profile ID for "my_account" is 0451343

{% hint style="warning" %} The connected user profile **must** have permission to "Insert Offline Conversions" in Google Campaign Manager 360 for the destination to work. This permission can be added from the User Roles screen. {% endhint %} Advertiser ID is an eight digit number associated with the advertiser that you are connecting to Freshpaint. It is found in several places throughout the Google Marketing Platform suite of products and may be referred to by terms such as "Floodlight configuration ID". One place it can be found on the "All advertisers" screen.

All advertisers screen in Campaign Manager 360. In this example, the advertiser ID for "My Advertiser" is 01234567

Once the Profile and Advertiser IDs have been specified, select "Connect with Google CM360" from the Freshpaint configuration page and follow the onscreen prompts to connect your Google account with CM360. Note that the Google account used to connect to CM360 should be the same account that the Profile ID was taken from in the previous step.
### Authentication There are two different methods that can be used to authenticate the connection between Freshpaint servers and Google. Only one of these approaches is necessary. #### User Account A user who has access to both Freshpaint and Google Campaign Manager 360 may delegate access to Freshpaint using the user account. Freshpaint will be granted the limited permissions necessary to send conversion events to google CM360 and be directly tied to the account of the user who delegated access. If that user account is removed or reset, google may revoke the authentication credentials that have been delegated to Freshpaint under that user account. {% hint style="info" %} The user delegating access to their User Account needs to have the "Insert offline conversions" permission as part of their role within Campaign Manager 360. {% endhint %} Navigate to `Apps > Destinations > Google Campaign Manager 360` and click either `Connect` or `Reconnect` in the `Access Permission` row of the destination configuration page. In the popup dialog select User Account and then `Connect with Google CM360` which will redirect you to Google to complete authentication and delegation of permissions to Freshpaint.
#### Service Account A user account within google can be created only for Freshpaint that will provide Freshpaint with a set of credentials that are not tied to any specific user. The creation of this account will require working with someone with necessary permissions within an underlying google cloud account to configure a service account. Please follow the Google documentation on the creation and configuration of a service account available at: {% hint style="info" %} The service account should be provided with the scope which will allow access to send conversion events to Google. {% endhint %} Once the service account has been created within Google, the credentials file can be uploaded to the Freshpaint application. Navigate to `Apps > Destinations > Google Campaign Manager 360` and click either `Connect` or `Reconnect` in the `Access Permission` row of the destination configuration page. In the popup dialog select `Service Account` and upload the json file with the credentials for Freshpaint to use and click save. ### Adding Required Properties For an event to be processed and successfully forwarded to CM360, the following properties are required*:* * `activity_id` — The 9-digit ID for the Floodlight Activity that conversions should be associated with. This may be added as an event transformation or directly sent with individual events. * Navigate to the [The Floodlight Activities Tab](https://support.google.com/campaignmanager/answer/2823234?hl=en) in CM360 to find this value. * `$dclid` — This is the double click ID used for the majority of click-through conversions. Enhanced attribution must be enabled in CM360 for conversions to work correctly; see below. An event still can be sent to CM360 without a `$dclid` present if one of `$edimpid` or `$gclid` is present on the event instead, but dclid always must be allowlisted. * `$edimpid` — This is used by view-through conversions with the Impression Pixel, and must be enabled to use the Impression Pixel. **Recommended Properties** * `$gclid` — This is used by Google's native advertising platforms, including Google Ads and Google Search Ads 360. You may want this enabled if you have CM360 connected to one of these platforms. If it is possible for gclids to come from a Google Ads account that is *not* connected to CM360, it is recommended to leave this off of events sent to CM360. * `match_id` — The custom unique match ID used for tracking conversions from your ad campaigns. Used as an alternative to standard Google identifiers (eg. `$edimpid`, `$dclid`, or `$gclid`) when the use case requires supplying a custom unique identifier from outside of CM360 for linking ad impressions to conversions. This might be helpful in scenarios where CM360 is involved in conversion attributions but is not being used as a server for the ad creative. [See Google's CM360 documentation for more information](https://developers.google.com/doubleclick-advertisers/guides/conversions_overview#using_match_id). Note that if an event has multiple identifiers on it, conversions sent to CM360 will use the most precise ID available to it, preferring `$dclid` first, `$gclid` second, `match_id` third, and `$edimpid` last. **Optional Properties** Freshpaint supports sending optional properties documented in the CM360 Conversions API to CM360. For more details on these fields and the underlying API, see .
Property NameDefault ValueDescription
quantity1The number of conversions to count with the event. Can be used with both Floodlight Counter and Floodlight Sales tags, though typically should be set to 1 for standard conversion counting.
value1.0The value associated with a conversion. Used with Floodlight Sales tags.
ordinalEvent-specific IDA deduplication ID used to prevent double-counting conversions. The default behavior is to use a unique ID per event, which should cover typical CM360 use cases.

Read more about De-duplicating conversions.
adDataUserConsentGRANTEDWhether or not consent has been granted. If present, must be set to "GRANTED" or "DENIED" Since Freshpaint already strips out disallowed user data from the request, this is set to granted by default.
childDirectedTreatmentnoneWhen set to true, indicates that an event may be associated with a user under the age of 13. Used for COPPA compliance purposes.
treatmentForUnderagenoneWhen set to true, indicates that an event may be associated with a user under the age of 16, country-dependent. Used for GDPR compliance purposes.
limitAdTrackingnoneWhen set to true, indicates the conversion will be used for reporting but not targeting and prevents remarketing.
nonPersonalizedAdnoneWhen set to true, indicates the conversion was for a non-personalized ad.
Freshpaint also supports transmitting Floodlight custom variables of the form `u1`, `u2`, `u3`...`u100`. Note that these values must be individually allowlisted in order to be sent. ### Linking a Freshpaint Event to a Floodlight Activity Each Floodlight tag in Campaign Manager uses an Activity ID value to uniquely identify the conversion action. Follow these steps to link your Freshpaint event to your Floodlight activity: 1. At the Advertiser level, navigate to Floodlight > Activities from the left nav and find the specific Floodlight activity you want to link your Freshpaint event. The value beside the activity name is the Floodlight tag's Activity ID (save this for later).
2. Attach the Activity ID to the related event in Freshpaint by creating a Transformation in Freshpaint: 1. Click on "Create New" in [Transformations](https://app.freshpaint.io/transformations) 2. Click "Modify Data" 3. Select your Freshpaint conversion event, select the Google Campaign Manager 360 Conversions API destination, then click "Save & Add Transformations"
4. Select the "Send Constant Property" transformation option, use activity\_id as the property name, and copy/paste the Activity ID value from step 1.
5. Click "Save" to complete your transformation rule {% hint style="info" %} If you're using Google Tag Manager and building a tag with the Freshpaint **Google Campaign Manager 360 Conversions API** tag type, make sure to map the `activity_id` value of the Floodlight tag into the Activity ID field within the tag configuration. Doing so will mitigate the need for you to set a transformation rule to link your Freshpaint event to the Floodlight activity, since the activity\_id value will already be in place from the GTM tag. {% endhint %} ### If you are a HIPAA account, you will need to add event properties to this destination's allowlist. If you are not a HIPAA account, you can skip this step. 1. Configure the destination's HIPAA Allowlist by navigating to Overview > DSP from the left nav and clicking Google Campaign Manager 360 Conversions API under the **Destinations** section. 2. Click on the "Configure" button beside the **Required Properties** row under the **Configuration** section 3. Ensure the `activity_id` property is allowlisted, along with other required properties for the destination. ### De-duplicating conversions The optional `counting_method` property can be used to override the default behavior of `ordinal` when a value for `ordinal` is not provided. There are 3 supported values for `counting_method`: 1. **"standard":** Default behavior. Counts every conversion. 2. **"unique":** Counts the first conversion for each unique user during each 24-hour day, from midnight to midnight, Eastern Time (US). 3. **"session":** Counts one conversion per user per session. Session length is set by the site where the Floodlight tag is deployed.

Counting method option in Google Tag Manager

If you are managing events through Freshpaint directly and not through Google Tag Manager, you can specify the counting method by following the steps below: 1. Click on "Create New" in [Transformations](https://app.freshpaint.io/transformations) 2. Click "Modify Data" 3. Select a specific event to apply the transformation to or select *All Events*, select the Google Campaign Manager 360 Conversions API destination, then click "Save & Add Transformations" 4. Select the "Send Constant Property" transformation option, use `counting_method` as the property name, and set the value to "standard", "unique", or "session".
5. Click "Save" to complete your transformation rule ### Click-through conversions To support click-through conversions with CM360, the enhanced attribution feature needs to be configured on the floodlight configuration used within CM360. Please see [Google Support - Enhanced attribution](https://support.google.com/campaignmanager/answer/9182069?hl=en) on how to configure dclids to be attached to landing page links. ### View-through conversions - Configuring an Impression PIxel To track view-through conversions on CM360, you will need to configure the [Freshpaint Impression Pixel](/integrations/impression-pixel) for the destination. In the impression pixel config screen within the destination configuration page for the CM360 destination, ensure one or both of IP or Cookie based matching is turned on. Note that these matches are only used by the Freshpaint application to match users to prior impressions; this information is *not* forwarded to the destination unless explicitly allowlisted.

Freshpaint impression pixel config. At least one form of matching must be enabled.

Copy the pixel configuration URL provided for use in CM360. On the advertiser in CM360, create a new Impression event tag with the "image" type and use URL from the Freshpaint configuration UI, as in the example screenshots below.

Impression event tags section in CM360

A newly configured Impression event tag. The "name" field can be any value. Tag Type should be "Image", enabled "Yes", and the URL should match the one provided by the Freshpaint config screen.

### Setting Up a Test Campaign in Google Campaign Manager 1. Coordinate with your marketing team or Agency partner who manages your campaigns 1. Let them know it’s a **small-scale test campaign** designed to validate tracking and performance. 2. Link your Freshpaint event(s) to a Floodlight activity/activities 3. Choose your creative and create a campaign 1. Use existing, current, or new creative—your choice! 4. Choose your channel 1. Target a channel that tracks clicks and views for more accurate validation 5. Set your budget 1. Keep it small ($10-50); aim for 1,000–3,000 impressions 6. Verify results 1. Ensure that click- and view-through conversions are tracking correctly both in Freshpaint and in your Campaign Manager account ### Verifying Conversion Reporting Once you have followed the steps above, you can verify that conversions are being reported to Google Campaign Manager **Event Verification** In Freshpaint, you can use the event verification tab to see which events are being successfully sent to Google Campaign Manager. You can also dig into each event to see the data being sent or investigate errors if there are any.
**Google Campaign Manager Reporting** Navigate to the **Reporting and Attribution** section. Under the Report Builder tab, create a new **Instant Report**:
Create an Activity report that breaks down the data by columns like view/click-through conversions and total conversion counts:
# StackAdapt Send advertising events directly to StackAdapt. {% content-ref url="/pages/iImBWUnfiFCeI3hFgAgz" %} [StackAdapt Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/stackadapt/stackadapt) {% endcontent-ref %} {% content-ref url="/pages/1gvRvxGTItnxX6LJ535u" %} [StackAdapt Reference](/integrations/destinations/demand-side-platforms-dsps/stackadapt/stackadapt-reference) {% endcontent-ref %} # StackAdapt Quick Start Guide Send advertising events directly to StackAdapt ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Audience retargeting, lookalikes, and exclusions](https://documentation.freshpaint.io/audiences/audience-integrations/stackadapt-audiences) * Refer to this destination as **StackAdapt** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### Configure Freshpaint destination 1. Make sure you have the appropriate access in both Freshpaint and StackAdapt: 1. Contact your Freshpaint Account Manager to request access to this destination. Once you have that, we will help you step by step through the configuration process. 2. Create your conversion funnel, and create events in Freshpaint to track your conversions. 3. Since StackAdapt only uses unique click IDs and Conversion Event IDs, there is no access token or Pixel ID required to set up the destination. 1. You can configure your [StackAdapt destination](https://app.freshpaint.io/destinations/apps/stackadapt) in Freshpaint by using the link provided here or by navigating to **Apps** > **StackAdapt** > **Configure** **StackAdapt** in the Freshpaint console. 2. In the destination, click the **Configure** button on the Configuration row and click **Save**.
Once you've [enabled](https://documentation.freshpaint.io/readme/setting-up-your-destinations/enabling-and-disabling-a-destination) the destination, you're ready to start setting up the campaign and conversion events in StackAdapt! ### Configure Conversion Events To send a conversion event to StackAdapt, you need to set up an event in StackAdapt and map your Freshpaint event to that event unique ID. #### In StackAdapt: 1. From the StackAdapt Pixel page, click **Create New** and select **Conversion Event**. 2. Select **Website** as the Install Location and **Page Load** as the Activation Method (even if you're not targeting page loads). 3. Select **Standalone Pixel** as the install method, leaving the default of Javascript. 4. Give your event a name, select the appropriate Conversion Category, and fill out any other fields relevant to the conversion event. Select **Create Pixel Code** once finished. 5. Click **Finish**, ignoring the autogenerated Javascript code. Copy the Conversion Event **Unique ID** for the newly created event once back on the Conversion Events dashboard. {% hint style="info" %} When setting up a conversion event in StackAdapt, you can select either 'click-through' or 'view-through and click-through'. 'View-through and click-through' is the default setting. When the default setting is enabled, the platform will attribute to both impressions and clicks. You convert the event in StackAdapt from 'click-through' to a 'view-through & click-through' at anytime. {% endhint %} #### To send an event to StackAdapt, you'll need to [enable the destination](/readme/setting-up-your-destinations/enabling-and-disabling-a-destination) for the event in Freshpaint: 1. If you'd like to send an autotrack event from your event library to StackAdapt, navigate to your Freshpaint event definition and toggle the destination on to enable the event to be sent to StackAdapt. You'll follow the steps below to add the Conversion Event Unique ID. If you're using Google Tag Manager, you can skip to step 2 below. 1. Return to the StackAdapt Destination in the Freshpaint console and configure a transformation to map one of your Freshpaint events to the StackAdapt Conversion Event. Click "Configure" next to "Event Transformations". 2. ```
``` 3. Click "**+ New Transformation**" 4. ```
``` 5. Select "**Modify Data**". Choose the event you'd like to send to StackAdapt, select the **StackAdapt** destination, click "**Enable it?**" if the event is not yet configured for StackAdapt, and click Save. 6. ```
``` 7. Once in the transformation edit page, add a new transformation of type Send Constant Property
8. Set the Property Value to the Conversion Event Unique ID (copied from the StackAdapt Conversion Events page), the Constant Type to Text, and the Property Name to `conversion_id`.
2. If you're using Google Tag Manager to send data to StackAdapt, you'd simply create a tag with the Freshpaint tag template in Google Tag Manager and select the tag type "StackAdapt". In this case, you just need to specify StackAdapt Conversion Event Unique ID in the event tag, no transformation necessary. Once you've set up the transformation with the StackAdapt Conversion Event Unique ID, you're ready to start sending events to StackAdapt via Freshpaint! ### Configuring StackAdapt for View-Through Conversions using the Freshpaint Impression Pixel For tracking view-through conversions with StackAdapt, we recommend using the [Freshpaint Impression Pixel](/integrations/impression-pixel). {% hint style="info" %} The Freshpaint platform previously supported doing view-through reallocation on StackAdapt directly by sending all potential conversions along with their IP. To ensure there's no disruption in conversion data, this legacy behavior continues to work if the impression pixel is not enabled and IP addresses are allowlisted. We recommend customers move to using the impression pixel as it minimizes the amount of data that needs to be sent to third parties and better ensures user privacy and compliance. {% endhint %} 1. Enable and the Freshpaint Impression Pixel for the StackAdapt destination. Copy the pixel configuration URL to your clipboard.
2. In your StackAdapt account, go to the campaign(s) you wish to enable view-through tracking on, and add the URL copied in step one to "Impression Tracking URLs"
3. Save the changes to your campaign. ### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. Freshpaint has the properties needed for StackAdapt conversion events listed under Required Properties. There are additional properties needed for Retargeting events listed under Recommended Properties. **Property Requirements:** * Conversion Events: `conversion_id`, `$sapid` * Retargeting Events: `retargeting_id`, `$ip`, `$user_agent`
{% hint style="info" %} When setting up a conversion event in StackAdapt, you can select either 'click-through' or 'view-through and click-through'. 'View-through and click-through' is the default setting. When the default setting is enabled, the platform will attribute to both impressions and clicks. You convert the event in StackAdapt from 'click-through' to a 'view-through & click-through' at anytime. {% endhint %} ### Set up Test Campaign and Configure in StackAdapt 1. Set up a test campaign that targets a small audiences and set a low budget ($10-50 budget). 2. In order for Freshpaint to be able to automatically capture the click ID auto-generated by the StackAdapt advertisement, the click ID needs to be specified as a macro in the campaign Click URL. 1. Navigate to the Overview tab in the StackAdapt portal, and click on your campaign. Click on the Creative tab and add `sapid={SA_POSTBACK_ID}` as a query parameter to your Click URL. A preview of the query parameters will show up under the Click URL that you can use to confirm that the query parameters are properly configured. 3. Verify in Freshpaint that the events triggering and flowing through to successfully to StackAdapt by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging) ### Confirm events are triggering and sending to StackAdapt successfully To check whether StackAdapt is receiving events, you can go to **Pixel > Conversion Events** within your StackAdapt account, which will show you when the last time StackAdapt received an event for each Conversion Event. {% hint style="info" %} Conversions may take up to 2 hours to appear in your StackAdapt portal {% endhint %} # StackAdapt Reference ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **StackAdapt** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Retargeting StackAdapt has extensive support for crafting audiences to retarget. By sending retargeting events to StackAdapt, you can craft campaigns to focus on audiences you know are already interested. {% hint style="warning" %} Retargeting Audiences with StackAdapt requires a user's IP Address and User Agent. When used with campaigns and ads that contain specific health information, sending a user's personally identifiable information (PII) for retargeting could be out-of-compliance with HIPAA unless a BAA is signed with StackAdapt. StackAdapt is not currently signing BAAs. {% endhint %} Retargeting Audience events require a `retargeting_id` in the same way Conversion Events require a `conversion_id`. The process to set up these events is the same. Following along with the conversion events guide above, we can create a **Transformation** that sends a **constant property** (`retargeting_id`) with the retargeting audience unique ID as the value. **Example**:
### Server-side You may provide the following additional event properties when sending events to StackAdapt via Freshpaint's servers: | **Event property** | **Type** | **Required?** | **Description** | | ------------------ | -------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$sapid` | string | Required for Click-Through Conversion Events | `sapid` is generated at ad click time and appended to the landing page URL. **Freshpaint will automatically capture sapid for events from your website**. For events from other sources you would need to provide `$sapid`. | | `conversion_id` | string | Required for Conversion Events | `conversion_id` maps to a Conversion Event in StackAdapt. This uniquely describes the conversion event taking place. | | `retargeting_id` | string | Required for Retargeting Events | `retargeting_id` maps to a Retargeting Audience in StackAdapt. This directly places the user in that Audience. | | `$ip` | string | Required for Retargeting Events and View-Through Conversion Events | Non-hashed public IP address of the browser | | `$user_agent` | string | Required for Retargeting Events | User agent from the user’s device | | `value` | string | Not required. Recommended for Conversion, Retargeting, and View-Through Conversion Events | Value of the conversion event, if any. | ## Considerations * Conversions may take up to 2 hours to appear in your StackAdapt portal. # Simpli.fi Conversions API (Early Access) Simpli.fi is a Connected TV (CTV) advertising platform that focuses on performance marketing. {% content-ref url="/pages/vKjzREFwlUHWnoyD68ao" %} [Simpli.fi Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/simpli.fi-conversions-api-early-access/simpli.fi-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/02IjhyjsSjTi2GPaci0d" %} [Simpli.fi Reference](/integrations/destinations/demand-side-platforms-dsps/simpli.fi-conversions-api-early-access/simpli.fi-reference) {% endcontent-ref %} # Simpli.fi Quick Start Guide This is a guide to help you get started on sending your conversion events to Simpli.fi via Freshpaint. If you've already completed set up and are looking for more information, see [Simpli.fi Reference](/integrations/destinations/demand-side-platforms-dsps/simpli.fi-conversions-api-early-access/simpli.fi-reference). {% hint style="warning" %} The Simpli.fi Conversions API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Simpli.fi** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Simpli.fi::123456.** You can retrieve this value from the Simpli.fi configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Simpli.fi audience key 2. Events in Freshpaint mapped to your Simpli.fi conversion audience ### Configure the Simpli.fi Conversions API destination in Freshpaint 1. Navigate to the [Freshpaint Destinations page](https://app.freshpaint.io/destinations/catalog). 2. Search for the Simpli.fi Conversions API destination. 3. Click Save on the Configuration row. 4. If you are a HIPAA account, it is highly recommended to set the Freshpaint allowlist for Simpli.fi to allow Freshpaint to forward the required properties. `audience_key` is required for all conversion events. `$sifi_transaction_id`, `$sifi_day`, and `$ip` are recommended for view-through attribution. `purchase_value_usd` and `purchase_order_id` are also recommended for e-commerce tracking. 5. Enable the [impression pixel](https://documentation.freshpaint.io/integrations/impression-pixel) for Simpli.fi. This enables Freshpaint to do view-through attribution within Freshpaint and report the conversion event to Simpli.fi. Then copy the `Pixel Configuration URL`. Click Save once you have set your preferred configuration options and copied the URL. 6. In your Simpli.fi account, navigate to the campaign(s) you wish to enable view-through tracking on and add the URL copied in step 5 to the impression tracking settings. This is required for view-through conversion tracking via Freshpaint. The URL that you paste in should look like: `https://freshpaint-impression.com/pixel.png?env_id=&dest_id=&$sifi_transaction_id={{transactionID}}&$sifi_day={{sifiDay}}` 7. Enable the Simpli.fi Conversions API destination. Once you've followed the steps above you can start sending events to Simpli.fi Conversions API. ### Set Up in Simpli.fi For each conversion event you want to track in Freshpaint, you will need to create a corresponding Conversion Audience in Simpli.fi. 1. Log in to your Simpli.fi account and open the First-Party Audiences screen. 2. Click **New Audience → Freshpaint Conversion** from the dropdown menu. 3. In the dialog window that opens: 1. Name the conversion audience. Note: do not include medically specific terms in the naming convention. 2. Select a **Conversion Event Type** (Other, Lead, Signup, or Purchase/Sale). 3. Click **Save**. 4. The audience will populate in the First-Party Audiences table. 4. Locate the conversion audience in the table, click the ••• menu on the right, then click **Copy Audience Key**. 5. Use this audience key when configuring your Send Constant Property transformation in Freshpaint (see Setting Up Conversion Events below). ### Setting Up Conversion Events To send a conversion event to Simpli.fi, each event must include an `audience_key` property that identifies the Simpli.fi conversion audience you want to attribute the conversion to. This value is provided by your Simpli.fi account team. Mapping a Freshpaint event to a Simpli.fi conversion audience 1. Navigate to the Simpli.fi Conversions API destination in Freshpaint and click Configure next to Event Transformations.
Simpli.fi destination configuration page with "configure" next to event transformations highlighted
2. Click "**+ Create New**". 3. Select "**Modify Data**". Choose the event you'd like to send to Simpli.fi, select the **Simpli.fi Conversions API** destination, click "**Enable it?**" if the event is not yet enabled for this destination, and click Save.
Freshpaint transformations page showing a Purchase event selected for the Simpli.fi Conversions API destination
4. Once in the transformation edit page, add a new transformation of type Send Constant Property. 5. Set the Property Name to `audience_key`, and the Property Value to your Simpli.fi conversion audience key provided by your Simpli.fi account team.
Transformation page showing example send constant property transformation for the property audience_key
6. Click Save. Once you've set up the transformation, Freshpaint will include the `audience_key` on every matching event sent to Simpli.fi. ### Sending Purchase Data (Optional) If you'd like to include purchase data with your conversion events, you can send `purchase_value_usd` and `purchase_order_id` as additional properties. These can be set in two ways: Using a Send Constant Property transformation (for fixed values): 1. In the same transformation edit page, add another Send Constant Property transformation. 2. Set the Property Name to `purchase_value_usd`, and the Property Value to the purchase amount in USD. 3. Optionally, add another Send Constant Property transformation with Property Name set to `purchase_order_id` and Property Value set to the order ID. If your events already capture purchase value and order ID as event properties, you can map them directly from your Event Definition without a transformation. Simply ensure the properties are named `purchase_value_usd` and `purchase_order_id` on the event, or use a Rename Property transformation to map your existing property names to these values.
Rename transformation example, renaming the property value to purchase_value_usd
### Verify Your Setup Once your integration is active: 1. Verify in Freshpaint that the events are triggering and flowing through successfully to Simpli.fi by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging). # Simpli.fi Reference This is a reference document for the Simpli.fi destination. For information on how to set up this integration, see the [Simpli.fi Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/simpli.fi-conversions-api-early-access/simpli.fi-quick-start-guide). {% hint style="warning" %} The Simpli.fi Conversions API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Simpli.fi** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Simpli.fi::123456.** You can retrieve this value from the Simpli.fi configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## View-Through Tracking Freshpaint supports view-through tracking by capturing the `$sifi_transaction_id` and `$sifi_day` parameters passed in by Simpli.fi using the Freshpaint Impression Pixel. Assuming you have followed the [Simpli.fi Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/simpli.fi-conversions-api-early-access/simpli.fi-quick-start-guide) to set up your destination, you can verify that view-through tracking is working by looking for an event in Event Verification that contains the `$sifi_transaction_id` and `$sifi_day` fields. You can also look for a transformation that shows the event data was enriched by the Freshpaint Impression Pixel.
Freshpaint transformation showing impression pixel match
For unattributed conversions (where no impression pixel match is found), if `$ip` is allowlisted, Freshpaint will send the user's IP address as a device identifier so Simpli.fi can still\ record the conversion. ## Relevant Properties | Freshpaint Property | Simpli.fi Parameter | Type | Required? | Description | | ---------------------- | -------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audience_key` | `audience_key` | string | Required | The Simpli.fi conversion audience key. Set via a Send Constant Property transformation. Identifies the Simpli.fi conversion audience to attribute the conversion to. | | `$sifi_transaction_id` | `transaction_id` | string | Recommended | The Simpli.fi unique identifier for impressions. Captured automatically by the Freshpaint Impression Pixel from the `{{transactionID}}` macro on your Simpli.fi creatives. Required for view-through attribution. | | `$sifi_day` | `sifi_day` | integer | Recommended | The internal Simpli.fi day identifier of the impression. Captured automatically by the Freshpaint Impression Pixel from the `{{sifiDay}}` macro on your Simpli.fi creatives. Required for view-through attribution. | | `$ip` | `device_id` | string | Recommended | The IP address of the user. Used as the device identifier for unattributed conversions when no impression pixel match is found. | | `purchase_value_usd` | `purchase_value_usd` | number | Recommended | The monetary value of the conversion event in US dollars. | | `purchase_order_id` | `purchase_order_id` | string | Recommended | A unique identifier for the purchase associated with the conversion. | # theTradeDesk Send advertising events directly to theTradeDesk {% content-ref url="/pages/LS3cDhgMVfZBSMWD21f9" %} [theTradeDesk Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/gZql1tbDbNm0QqgsJxrD" %} [theTradeDesk Reference](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-reference) {% endcontent-ref %} {% content-ref url="/pages/UmbmvCoWWL0olIN4DmyB" %} [theTradeDesk with CM360 Configuration Guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-with-cm360-configuration-guide) {% endcontent-ref %} # theTradeDesk Quick Start Guide Send advertising events directly to theTradeDesk ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **theTradeDesk** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **theTradeDesk::4w1ba8e.** You can retrieve this value from theTradeDesk configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your theTradeDesk Advertiser ID 2. Image Pixel IDs / tracker\_ids for your conversions 3. Advertising media configured in your theTradeDesk account to specify `ttdimp` 4. Advertiser ID configured in Freshpaint 5. Conversion Events configured in your Freshpaint account, or GTM tags using the [Google Tag Manager integration](/integrations/google-tag-manager-integration) ### To set up theTradeDesk with Freshpaint, follow these steps: 1. Make sure you have the appropriate access in both Freshpaint and theTradeDesk: 1. Contact your Freshpaint Account Manager to request access to this destination. Once you have that, we will help you step by step through the configuration process 2. Contact your Agency & theTradeDesk pod to complete necessary legal documentation. These documents are referred to as ‘API Order Form’ and ‘Access Letter’. These documents are required by theTradeDesk to set up Freshpaint on your theTradeDesk account. 2. Create your conversion funnel, and create events in Freshpaint to track your conversions. 3. Find the Advertiser ID in your [theTradeDesk account](https://desk.thetradedesk.com/). Be sure you have the desired Advertiser selected, then find the Advertiser ID from the URL when navigating to Inventory -> Site/App in theTradeDesk UI. It should look similar to 4w1ba8e:
4. Set up an Image Pixel in theTradeDesk 1. The owner of theTradeDesk account will need to apply for legal for approval (vendor attribution) for all new pixels through theTradeDesk. This is required by theTradeDesk. 5. Get the Image Pixel ID(s) for your conversions. These may be found by navigating to Data -> Image Pixels in theTradeDesk UI (if using the [Google Tag Manager integration](/integrations/google-tag-manager-integration), these are populated from your migrated theTradeDesk Static Tracking Tags):
6. For click through conversions: 1. Creatives hosted in theTradeDesk: Configure all media assets used by your theTradeDesk account to include `ttdimp` in the landing page URL:\ `ttdimp=%%TTD_IMPRESSIONID%%` 2. Creatives hosted in CM360: Refer to [this guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-with-cm360-configuration-guide) once you have followed the rest of the steps on this page. 7. Go to the [theTradeDesk configuration page](https://app.freshpaint.io/destinations/apps/thetradedesk) in Freshpaint and configure the Advertiser ID:\
8. (Optional) For view-through conversions: 1. In order to track view through conversions with theTradeDesk, enable the [Impression Pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)from the Freshpaint configuration page. See [View Through Conversions](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-reference#view-through-conversions) for more detailed instructions on this step. 2. You'll need to apply the Freshpaint Impression Pixel to your campaign creative in theTradeDesk {% hint style="warning" %} If you use CM360 as your Ad Tech Platform, please follow [this guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-with-cm360-configuration-guide) once you are done configuring theTradeDesk destination in Freshpaint. {% endhint %} ### Required Properties {% hint style="info" %} The following event properties are **required** in order to attribute events to specific ads, and if in HIPAA mode, must be selected in the Required Properties Allow List. {% endhint %}
Freshpaint propertytheTradeDesk
parameter		TypeDescription
$ttdimpAll advertising media must include the following in the URL:

ttdimp=%%TTD_IMPRESSIONID%%		stringttdimp (theTradeDesk impression ID) is generated at ad bid time and appended to the landing page URL. Freshpaint will automatically capture ttdimp for events from your website. If you wish, you may provide $ttdimp as an event property to override the automatically captured value.
tracker_idtracker_idstringThe Image Pixel ID associated with a conversion, as described above.
There are other optional parameters you can add to your events in order to achieve different use cases. You can view the full list of parameters [here](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-reference). ### To send an event to theTradeDesk, you'll need to enable the destination for the event: If you'd like to send an autotrack event from your event library to theTradeDesk, navigate to your Freshpaint event definition and toggle the destination on to enable the event to be sent to theTradeDesk:
If you've configured multiple Advertiser IDs, you'll need to toggle each pixel individually for each Freshpaint event. If you're using Google Tag Manager to send data to The Trade Desk, you'd simply create a tag with the Freshpaint tag template in Google Tag Manager and select the tag type "theTradeDesk". If you have multiple Advertiser IDs enabled for theTradeDesk, you'll need to specify which Advertiser ID(s) you'd like to enable the event for in the event tag. {% hint style="info" %} You'll need to include the image pixel ID from theTradeDesk with the conversion event. You can do with by creating a constant property [transformation](https://documentation.freshpaint.io/admin-panel/transformations) in Freshpaint. {% endhint %} ### Set up a test campaign in theTradeDesk 1. Set up a test campaign that targets a small audiences and set your budget to 1000 impressions ($10-50 budget) 2. Attach a creative that has the Freshpaint Impression Pixel 3. Verify impressions and clicks are flowing into Freshpaint correctly by working with your Customer Success Engineer 4. Verify in Freshpaint that the events triggering and flowing through to successfully to theTradeDesk by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging) ### Confirm and Validate Conversions in theTradeDesk Congratulations! Once you have confirmed conversion in theTradeDesk, you have finished setting up this integration. You can find more detailed documentation on this integration in the [theTradeDesk Reference](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-reference) # theTradeDesk Reference Send advertising events directly to theTradeDesk ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **theTradeDesk** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **theTradeDesk::4w1ba8e.** You can retrieve this value from theTradeDesk configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the theTradeDesk destination. For information on how to set up this integration, see the[ ](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide)[theTradeDesk Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-quick-start-guide) ### Events When you send an event to theTradeDesk from Freshpaint, Freshpaint will create an event in theTradeDesk by hitting theTradeDesk's [Real-Time Conversion Events endpoint](https://partner.thetradedesk.com/v3/portal/data/doc/DataConversionEventsApi) in theTradeDesk. ## Track Events When you send an event to theTradeDesk, you can track conversions from your ads based on those events. Below are the Required, Recommended, and Optional properties which are mapped to theTradeDesk request:
Freshpaint
property		theTradeDesk
parameter		TypeRequired?
Recommended?		Description
$ttdimpimpstringRequiredA 36-character string (including dashes) that serves as the unique ID for the impression to which the event is attributed.

When in HIPAA mode, is a Required Allow List property.
tracker_idtracker_idstringRequiredThe platform ID of the event tracker. Example value: hc7ihke

When in HIPAA mode, is a Required Allow List property.
valuevaluenumberOptionalWhen specified, the default currency is used.
privacy_settingsprivacy_settingsobjectOptionalUser privacy settings based on data privacy consent processing. For object properties, see Privacy Settings Properties.
data_processing_optiondata_procession_optionobjectOptionalA data processing option to pass users' opt-out choices, such as Limited Data Use (LDU), in applicable US states. This is an alternative to the GPP string in the privacy_settings, see Data Processing Options
### Click-Through Conversion For click-through conversions some additional configuration is needed on creatives within the trade desk. A macro will need to be added to the landing page URL that will cause theTradeDesk to include the impression id as part of the URL of the click. Freshpaint will automatically look for the URL parameter of `ttdimp` when installed on the page. ### View-Through Conversions Freshpaint can track view-through conversions and send them to theTradeDesk using the [Freshpaint Impression Pixel](/integrations/impression-pixel). On the impression pixel configuration dialog within the destination configuration page within Freshpaint ensure that either IP or Cookie based matching is turned on. Also ensure any creatives within theTradeDesk are configured to include the pixel URL and setting provided within the destination configuration page. {% hint style="warning" %} If you use CM360 as your Ad Tech platform, please refer to this [setup guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-with-cm360-configuration-guide) once you have finished setting up theTradeDesk destination in Freshpaint {% endhint %}

Impression Pixel config in theTradeDesk destination configuration

{% hint style="info" %} Configuring the impression pixel does not require sharing an IP address or Cookie with theTradeDesk. Freshpaint will do the attribution by matching either the IP address or Cookie to an impression that is seen by the Freshpaint Impression Pixel and if a match is found will send the impression id to theTradeDesk. {% endhint %} There are a couple of options for adding the Freshpaint Impression Pixel to your existing Trade Desk creatives. 1. Manually append the pixel in The Trade Desk's `Add Creative` Ul by adding the pixel into the "1x1 Pixel Impression Tracking URL" or "JavaScript Tracking Tag" field.
2. Set a "Default" Impression Tracking URL in The Trade Desk, which will automatically append any pixel onto all creatives uploaded under your Advertiser seat. Note: this option requires outreach to your The Trade Desk CS team member who can help grant access to this option.
# theTradeDesk with CM360 Configuration Guide This configuration guide will walk you through how to use theTradeDesk and Campaign Manager 360 (CM360) together with Freshpaint. {% hint style="warning" %} These instructions assume that you have already set up theTradeDesk destination in Freshpaint. If you have not yet done so, please refer to [theTradeDesk Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-quick-start-guide). Please note that configuring the CM360 destination in Freshpaint is not required in order to send events to theTradeDesk. {% endhint %} ## Introduction theTradeDesk is able to use Google Campaign Manager 360 as the Ad Tech platform to manage campaigns. When theTradeDesk and Google Campaign Manager 360 are integrated with each other, some changes to the Google Campaign Manager 360 configuration are required to allow Freshpaint to collect the necessary parameters to perform ad optimization. This guide walks through the changes that are required. {% hint style="info" %} This guide assumes theTradeDesk and Google Campaign Manager 360 accounts are already integrated with each other. If Google Campaign Manager 360 and theTradeDesk are not already configured to work together, please configure them first as per the recommendations of theTradeDesk. {% endhint %} ### Click-Through Conversions Click-through conversions occur when a visitor clicks on an ad that is shown to them and is taken to a landing page configured within the creative. Campaigns in theTradeDesk may have limited or no click-through activity. If you expect click-through activity to occur, Campaign Manager 360 can be configured to append a unique identifier for the ad impression to the landing page URL. If Freshpaint is installed on the landing page, then Freshpaint can capture the impression id to be used if the website visitor converts. ### View-Through Conversions View-through conversions occur when a visitor views an ad and then sometime later visits a website and converts. Freshpaint is able to attribute view-through conversions if CM360 is configured to show an impression pixel when ads are served. This allows Freshpaint to track an ad impression, and do attribution when a conversion event is processed by Freshpaint servers. #### Methods of Attribution Freshpaint currently supports two methods for identifying if a website visitor has viewed an ad: 1. IP Address - An Internet Protocol address is the address used by computers to communicate with each other over the internet. Internet Protocol addresses have some limitations in that they do not uniquely identify a device, and many devices can share a particular address, or change their addresses at various times. Because of this IP address based matching will have an associated error rate, with both false positives and false negatives occurring. Freshpaint does not currently have any estimates on how accurate IP address based matching is.\ \ If you are showing ads on Connected TV devices, in Freshpaint's experience it is rare for the conversion to occur on the Connected TV itself. In this case Freshpaint recommends use of IP address based attribution for advertising campaigns targeted at connected TV. 2. Cookie - A cookie is a small piece of information that can be set on a web browser that the web browser will then include in each web request made to our servers afterwards. When an ad is viewed, the Freshpaint impression pixel can set a unique browser identity as a cookie in the visitors web browser. When the visitor later lands on a website and converts, the unique identity is used to look up any ad impressions that were seen by the same device and browser.\ \ Using cookie based matching is only recommended in advertising campaigns where the user is expected to convert on the same device and web browser as was shown the ad. If a user converts on a different device or web browser than was shown the cookie will not match. Some web browsers such as Firefox and Safari block the required cookie functionality for attribution to occur. {% hint style="info" %} IP address and Cookie attribution can both be enabled. {% endhint %} {% hint style="info" %} Freshpaint performs attribution in the following order: 1. Click-through 2. Cookie 3. IP Address View-through attribution will only fire if a click-through isn't detected. If the Cookie is disabled or a match isn't found, than IP address will be attempted. {% endhint %} #### Conversion Windows When configuring View-through conversions in Freshpaint a conversion window is used to select how far back an event should look for a matching ad impression. When a conversion event is processed by Freshpaint, it will use the conversion window to select only ad impressions that have occurred within the configured number of days. If there are multiple impressions that match, only the most recent will be used. {% hint style="info" %} The attribution ordering described above applies to the attribution window. As an example, we have a cookie impression 5 days ago and an IP address impression 1 day ago. If the conversion window is configured as 10 days, than the attribution will select the IP address match from 5 days ago, because a cookie match is preferred of an IP address match even if the IP address based impression is more recent. If the conversion window is configured as 3 days ago, the attribution will select the IP address based impression, because the Cookie based impression is outside the conversion window and that leaves only the IP address based impression as valid. {% endhint %} {% hint style="info" %} Changes to the conversion window configuration in a destination will take effect immediately once saved. {% endhint %} ## Configuration ### Common Configuration The following configuration is required whether you are doing Click-through or View-through conversions within CM360. 1. Log into Campaign Manager 360 2. Navigate to the Campaign you want to configure. 3. Edit a placement you want to enable click-through for 4. Expand `Tag defaults` 5. Add an additional key-values entry of 1. Key: `ttdimp` 2. Value: `%%TTD_IMPRESSIONID%%`
### Configuring Click-through The following configuration is required within CM360 to enable Click-through conversion attribution. 1. Log into Campaign Manager 360 2. Configure the Advertiser to impact all ads or navigate to an individual Ad. 1. Advertiser: Navigate to the Advertiser Properties and set the Landing page URL suffix to `ttdimp=%pttdimp=!;`
2. Ad: Navigate to the campaign you want to configure and configure the Ad(s) you want to configure. Add the `ttdimp=%pttdimp=!;`macro to the landing page URL to set the ttdimp URL parameter to the landing page. 1. Examples: 1. ?ttdimp=%pttdimp=!; 2. ttdimp=%pttdimp=!;
### Configuring View-through #### Freshpaint Configuration 1. Ensure you have a destination configured as per [theTradeDesk Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/thetradedesk/thetradedesk-quick-start-guide) 2. Navigate to the destination settings configuration page
3. Select Configure for the Freshpaint Impression Pixel 4. Enable the Matching options you wish to use and set the number of days for the conversion window
5. Select Copy next to the CM360 Pixel URL to copy the impression pixel URL that will need to be configured in CM360 {% hint style="warning" %} The configuration dialog provides URLs for when configuring the Pixel on theTradeDesk and a separate URL when configuring CM360. Make sure to use the "CM360 Pixel URL". {% endhint %} #### CM360 Configuration The Freshpaint Impression Pixel can be configured as an advertiser or campaign event tag. 1. If configuring at the Advertiser level, navigate to the Advertiser Properties and open the Event tags configuration. 2. If configuring at the campaign level, navigate to the Campaign Properties and open the Event tags configuration. 3. Create a new impression event tag 1. For Tag type, select Image 2. For Tag URL, copy the URL retrieved from Freshpaint above
#### Testing the CM360 Configuration Whether CM360 is correctly configured can be tested independent of theTradeDesk by exporting the tags. 1. Navigate to the Campaign you want to verify 2. In the upper right corner Select Tags > Download Tags
3. In the download page 1. Select HTML as the Format 2. Select the placements you want to verify 3. Click Download 4. Open the downloaded file in a web browser 5. Copy one of the tags that looks like ` and paste the tag somewhere in the body of the page. 7. Change the `%%TTD_IMPRESSIONID%%` to be a value, such as 1234
**To test click-through** 1. In the w3school tool select `Run` to generate the website with the embedded advertisement 2. Click on the ad 3. Check that the URL on the landing page contains the text ttdimp=\ where value is what you set above.
{% hint style="warning" %} Some landing pages are configured to redirect the browser to another page. If Freshpaint is installed on the landing page it will automatically capture the ttdimp property from the URL, but the URL you see may not show the ttdimp=\. This is working as expected as Freshpaint will save the ttdimp value. If Freshpaint is not installed on your landing page that redirects, you will need to coordinate with your web team to ensure the landing page when redirecting the user also forwards the ttdimp parameter to the next page with Freshpaint installed. {% endhint %} **To test view-through** {% hint style="info" %} If you are not familiar with the dev tools of you're browser you can find more information here: {% endhint %} 1. Open the browser Dev Tools and select the network tab. 2. In the w3school tool select `Run` to add the tag to the page on the right 3. Look for an HTTP request that goes to and includes $ttdimp=\ where the value is what you selected above.
# Viant Viant's DSP is a demand side platform that enables you to reach your target customers with DSP ads seamlessly across all programmatic channels and formats. {% content-ref url="/pages/XX9DSrM3VSZmcxTE1r9d" %} [Viant Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/viant/viant-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/ytGgOXYhJN9WYAHjWYWh" %} [Viant Reference](/integrations/destinations/demand-side-platforms-dsps/viant/viant-reference) {% endcontent-ref %} # Viant Quick Start Guide Send advertising conversion events directly to Viant's DSP. This is a guide to help you get started on sending your conversion events to Viant via Freshpaint. If you've already completed set up and are looking for more information, see [Viant Reference](/integrations/destinations/demand-side-platforms-dsps/viant/viant-reference). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Audience retargeting, lookalikes, and exclusions](https://documentation.freshpaint.io/audiences/audience-integrations/viant-audiences) * Refer to this destination as **viant** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **viant::123456.** You can retrieve this value from Viant configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Viant Advertiser ID 2. Advertiser ID configured in Freshpaint 3. \[If in HIPAA mode] Allowlist set up to allow Freshpaint to forward `viant_clid` and `viant_impid` to Viant 4. [Impression pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)enabled to allow Freshpaint to do view through conversion attribution 5. Advertising media configured in your Viant account to specify `viant_clid` and `viant_impid` for click through and view through conversions respectively. ### To set up Viant with Freshpaint, follow these steps: 1. Make sure you have the appropriate access in both Freshpaint and Viant: 1. Contact your Freshpaint Account Manager to request access to this destination. Once you have that, we will help you step by step through the configuration process. 2. Create your conversion funnel, and create events in Freshpaint to track your conversions. 2. Find your Advertiser ID in your Viant account.

Grab your Advertiser ID

3. Set the Advertiser ID in Freshpaint.

Set the Advertiser ID in Freshpaint.

4. \[If in HIPAA mode] Set the Freshpaint allowlist for Viant to allow Freshpaint to forward `viant_clid` and `viant_impid` to Viant. These are required properties for the destination to be able to forward conversion events to Viant.

Required allowlist settings while in HIPAA mode

4. Enable the [impression pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)for Viant. This enables Freshpaint to do view through attribution within Freshpaint and report the conversion event to Viant. We recommend enabling both IP matching and Cookie matching, and setting the Conversion Window to 30 days for the best results. Then copy the `Pixel Configuration URL` for step 5(b). Click `Save` once you have set your preferred configuration options and copied the url.

Impression Pixel for Viant

{% hint style="info" %} Configuring the impression pixel does not require sharing an IP address or Cookie with Viant. Freshpaint will do the attribution by matching either the IP address or Cookie to an impression that is seen by the Freshpaint Impression Pixel, and if a match is found, will send the impression id to Viant. {% endhint %} 5. Configure your media within Viant. This will allow Freshpaint to capture the click and view impression IDs to be able to send Viant conversion events. The parameters added here are also the ones that are required to be allowlisted. 1. **For the Landing Page URL**: add a query parameter `viant_clid=${ADELPHIC_CLICKID}` to your landing page URL to capture the click ID. This is required for click through conversion tracking via Freshpaint. For example, it should look like `https://landingpageurl.com/abc?viant_clid=${ADELPHIC_CLICKID}` 2. **For the Tracking Pixels (Pixel 1)**: Set the URL that you copied in step 4. This is required for view through conversion tracking via Freshpaint. The URL that you paste in should look like `https://freshpaint-impression.com/pixel.png?env_id=&dest_id=&cke=1&$viant_impid=${ADELPHIC_CLICKID}`

Configure your creative in Viant

### Set up a test campaign in Viant 1. Set up test campaign with a low budget (1$) to a target ‘Deal ID’ in Viant. You'll be able to obtain this value from your Customer Success Engineer. 1. Select New Client Deal
b. Fill out highlighted fields then click "Create Client Deal"
c. Assign your creative to the test campaign/order/line (Supported sizes: 300x250, 728x90, 160x600, 300x600) and Target the test deal in your line along with US geo.
2. Navigate to page where ad is displayed, click through into your funnel (follow user steps that lead to your conversion event) 3. Verify in Freshpaint that the conversions are triggering in Live View 4. Verify in Freshpaint that conversions are flowing through to Viant via Event Verification and your conversions are displaying on the campaign in Viant as expected (see more on this below) ### Verifying conversion reporting Once you have followed the steps above, there are multiple ways you can verify that conversions are being reported to Viant: #### Event Verification On Freshpaint, you can use the event verification tab to see which events are being successfully sent to Viant. You can also dig into each event to see the data being sent or investigate errors if there are any.

Event Verification

#### Reporting Viant provides conversion event reporting through a dedicated Healthcare Conversions report. Self-service DSP clients can subscribe to the Healthcare Conversions report on the Measurement tab of the Advertiser level. Viant will subscribe managed-service DSP clients.
## Further reading Looking for more information? See [Viant Reference](/integrations/destinations/demand-side-platforms-dsps/viant/viant-reference). # Viant Reference Send advertising conversion events directly to Viant's DSP. This is a reference document for the Viant destination. For information on how to set up this integration, see the [Viant Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/viant/viant-quick-start-guide). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **viant** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **viant::123456.** You can retrieve this value from Viant configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Click Through Tracking Freshpaint supports click through tracking by capturing the `viant_clid` query parameter on the landing page configured on your creative. You need to have the Freshpaint javascript snippet installed on the landing page for this to work. Assuming you have followed the [Viant Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/viant/viant-quick-start-guide) to set up your Viant destination, you can verify that click through tracking is working by looking for an event in event verification that contains the `$viant_clid` field.

Event verification

Click ID being captured

## View Through Tracking Freshpaint supports view through tracking by capturing the `viant_impid` passed in by Viant using the Freshpaint Impression Pixel. Assuming you have followed the [Viant Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/viant/viant-quick-start-guide) to set up your Viant destination, you can verify that view through tracking is working by looking for an event in event verification that contains the `$viant_impid` field, similar to how you can verify Click Through Conversion. You can also look for a transformation that shows that the event data was enriched by the Freshpaint Impression Pixel.

Transformation applying the Impression Pixel captured impression to an event

## Relevant Properties These are the properties that are sent to Viant. If you've followed the [Viant Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/viant/viant-quick-start-guide) correctly, no further action is necessary. This section is just informational.
Freshpaint propertyViant
parameter		TypeDescription
$viant_clidxidstringThis is the Viant Click ID that is captured by the Freshpaint tracker on the landing page configured on the creative. This is a required property, but can be empty if it's a view through conversion. This takes priority over the view impression ID.
$viant_impidimp_idstringThis is the Viant View Impression ID. This property is captured by the Freshpaint Impression Pixel, and is passed to Freshpaint via the tracking pixel configured on the creative. This is a required property, but can be empty if it is a click through conversion.
<event_name>ci_t_event_name
p_event_name		stringEvent name property for Viant. Freshpaint automatically sets both Viant parameters to the event name.
<advertiser_id>c_advertiser_idnumeric stringThis is your Viant Advertiser ID that you configure on Freshpaint when setting up the destination. Required.
<event_time>p_event_timenumberThis is the event time represented in ms since epoch. Automatically set by Freshpaint.
-ci_t_vendorstringHardcoded to freshpaint. Automatically set by Freshpaint.
-ci_t_actionstringHardcoded to tx_created. Automatically set by Freshpaint.
# Vibe Conversions API (Early Access) Vibe is a Connected TV (CTV) advertising platform that focuses on performance marketing. {% content-ref url="/pages/xPvXm2ji3YbJCwyhm6DR" %} [Vibe Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/fNGLh13nJ3sNSQHQv4Eh" %} [Vibe Reference](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-reference) {% endcontent-ref %} # Vibe Quick Start Guide This is a guide to help you get started on sending your conversion events to Vibe via Freshpaint. If you've already completed set up and are looking for more information, see [Vibe Reference](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-reference). {% hint style="warning" %} The Vibe Conversions API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Vibe Conversions API** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Vibe Conversions API::123456.** You can retrieve this value from the Vibe configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Vibe Pixel ID 2. Pixel ID configured in Freshpaint 3. Events in Freshpaint mapped to a valid Vibe event type ### Get your Vibe Pixel ID 1. In your Vibe dashboard, navigate to [Tracking → Web Pixel](https://www.vibe.co/dashboard/settings/tracking/web). 2. Click "Set up a Pixel".
Image of the Vibe dashboard, highlighting the "Set up a pixel" button in the top right corner.
3. Under Choose an installation method, select Google Tag Manager. You do not need to complete the Google Tag Manager installation - this step is only to locate your Pixel ID.
Installation methods with "Google Tag Manager" selected.
4. Select your advertiser. 5. Click "Continue" and copy the Pixel ID displayed on this page.
Vibe dashboard showing where to copy pixel ID
### Configure the Vibe Conversions API destination in Freshpaint 1. Navigate to the [Freshpaint Destinations page](https://app.freshpaint.io/destinations/catalog). 2. Search for the Vibe Conversions API destination. 3. Select Configure to paste your Pixel ID from the above steps. 4. Customers that use HIPAA mode should then configure the required, recommended, and recommended view-through properties. You can find all properties that the Freshpaint Vibe Conversions API integration supports [here](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-reference#events). 5. Enable Vibe Conversions API. Once you've followed the steps above you can start sending events to Vibe Conversions API.
Image of the Freshpaint Vibe Conversions API configuration settings, showing where to set Pixel ID
### Setting up Conversion Events Now that you've configured Freshpaint to connect to your Vibe pixel, you can send events to Vibe to track specific conversion types. Vibe supports 5 conversion event types: `install`, `lead`, `page_view`, `purchase`, and `signup`. Freshpaint will automatically match an event to a Vibe event type if the event name, after lowercasing and inserting underscores at camelCase boundaries, exactly matches one of the valid types. For example, "Purchase", "purchase", and "PURCHASE" all match `purchase`, and "PageView" or "pageView" match `page_view`. Note that space-separated names like "Page View" will not match. If you'd like to use an existing Freshpaint event whose name does not match a valid Vibe event type, you can use a Rename Event transformation to align the event name before it's sent to the destination. To do so: 1. Navigate to the [Transformations page](https://app.freshpaint.io/transformations) in Freshpaint. 2. Add a **Rename Event** transformation to map your existing event name to a valid Vibe event type (`install`, `lead`, `page_view`, `purchase`, or `signup`).
Freshpaint transformations page displaying a "Rename Event" transformation to rename event to a valid Vibe event type.
Events that cannot be resolved to a valid Vibe event type will be dropped. #### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Go to the Vibe Conversions API configuration page in Freshpaint. 2. Click "Configure" next to "Required Properties" and "Recommended Properties".
Vibe Conversions API configuration page with "Configure" highlighted next to "recommended" and "required" properties
### Confirm and Validate Events #### Confirm and Validate Conversions in Freshpaint 1. Navigate to your site and trigger an event that should be sent to Vibe. 2. Navigate to the [Event Verification tool](https://app.freshpaint.io/event-verification) in Freshpaint. 3. Select **Vibe Conversions API** and verify your event went through. 4. Verify the event is marked as OK or resolve any missing property issues. #### Confirm and Validate Conversions in Vibe To check whether Vibe is receiving your events: 1. Log in to your Vibe account. 2. Navigate to [Tracking → Web Pixel](https://www.vibe.co/dashboard/settings/tracking/web). 3. You should see conversion events appearing for your pixel. # Vibe Reference This is a reference document for the Vibe destination. For information on how to set up this integration, see the [Vibe Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-quick-start-guide). {% hint style="warning" %} The Vibe Conversions API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Vibe Conversions API** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Vibe Conversions API::123456.** You can retrieve this value from the Vibe configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the Vibe Conversions API destination. For information on how to set up this integration, see the [Vibe Conversions API Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/vibe-conversions-api-early-access/vibe-reference). ### Events #### Required Properties | Freshpaint Property | Vibe Parameter | Type | Requirement | Description | | ------------------- | -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------ | | `$ip` | `ip` | string | Required | IP address of the user who performed the action. Events are dropped if this property is missing. | #### Recommended Properties | Freshpaint Property | Vibe Parameter | Type | Requirement | Description | | ------------------- | ---------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vibe_event_name` | `a` | string | Recommended |

Vibe event type. Valid values: install, lead, page\_view, purchase, signup. If not set, Freshpaint will attempt to derive the event type by lowercasing
the event name and inserting underscores at camelCase boundaries (e.g., "Purchase" → purchase, "PageView" → page\_view). Note that space-separated names
(e.g., "Page View") will not match. Events that cannot be resolved to a valid type will be dropped.

| | `revenue` | `ed.price_usd` | number | Recommended | Purchase amount in USD. `revenue` takes precedence over `price_usd` if both are present. Recommended for purchase events. | | `order_id` | `ed.purchase_id` | string | Recommended | Unique order identifier. `order_id` takes precedence over `purchase_id` if both are present. Recommended for purchase events. | #### Recommended View-Through Properties | Freshpaint Property | Vibe Parameter | Type | Requirement | Description | | ------------------- | -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------- | | `$user_agent` | `ua` | string | Optional | User agent string of the user's browser or device. Automatically captured by Freshpaint when available. | # MNTN MNTN is a Connected TV (CTV) advertising platform that focuses on performance marketing. {% content-ref url="/pages/Tv4RiPHLdrlWzkyaRdps" %} [MNTN Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/X6NKCuau48ODzG2aXttN" %} [MNTN Reference](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-reference) {% endcontent-ref %} # MNTN Quick Start Guide This is a guide to help you get started on sending your conversion events to MNTN via Freshpaint. If you've already completed set up and are looking for more information, see [MNTN Reference](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-reference). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Refer to this destination as **MNTN** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **MNTN::123456.** You can retrieve this value from the MNTN configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your MNTN Advertiser ID 2. Advertiser ID configured in Freshpaint 3. \[If in HIPAA mode] Allowlist set up to allow Freshpaint to forward properties to MNTN for attribution 4. [Impression pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)enabled to allow Freshpaint to do view through conversion attribution 5. Advertising media configured in your MNTN account to specify `mntn_impid` for view through conversions. ### To set up MNTN with Freshpaint, follow these steps: 1. Make sure you have the appropriate access in both Freshpaint and MNTN: 1. Contact your Freshpaint Account Manager to request access to this destination. Once you have that, we will help you step by step through the configuration process. 2. Create your conversion funnel, and create events in Freshpaint to track your conversions. 2. Find your Advertiser ID in your MNTN account. It is the number in parenthesis in the top right of the page, alongside your account name. Reference the [MNTN documentation](https://help.mountain.com/en/articles/12159399-find-your-advertiser-id) for help finding your advertiser ID.

Example: advertiser ID is 12345, in the top right of the screen

3. Set the Advertiser ID in Freshpaint.
4. \[If in HIPAA mode] It is highly recommended to set the Freshpaint allowlist for MNTN to allow Freshpaint to forward `mntn_impid`. This property will allow Freshpaint and MNTN to perform attribution on your conversion events. The `order_id` is also recommended for e-commerce tracking.
5. Enable the [impression pixel ](https://documentation.freshpaint.io/integrations/impression-pixel)for MNTN. This enables Freshpaint to do view through attribution within Freshpaint and report the conversion event to MNTN. We recommend enabling IP matching and setting the Conversion Window to 30 days for the best results. Freshpaint automatically looks back an additional 14 days for verified visits meaning the total lookback window is a minimum of 44 days. Then copy the `Pixel Configuration URL` for step 6(a). Click `Save` once you have set your preferred configuration options and copied the url.

Impression pixel setup for MNTN

{% hint style="info" %} Configuring the impression pixel does not require sharing an IP address with MNTN, though sharing the IP is recommended for MNTN to perform attribution. Freshpaint will do attribution by matching the IP address to an impression that is seen by the Freshpaint Impression Pixel, and if a match is found, will send the impression id to MNTN. {% endhint %} 6. Configure your media within MNTN. This will allow Freshpaint to capture view impression IDs to be able to send MNTN attributable conversion events. The parameters added here are also the ones that are required to be allowlisted. 1. **For impression tracking**: Under "My Account" > "Integrations" find the Freshpaint integration. Click "Connect". In the modal, paste the URL from step 5 and click "Save". This is required for view through conversion tracking via Freshpaint. The URL that you paste in should look like `https://freshpaint-impression.com/pixel.png?env_id=&dest_id=&cke=1&$mntn_impid=${asid}`.
{% hint style="warning" %} You may see the warning *Macro "asid" is not valid* when you paste the impression URL. This can be safely ignored. {% endhint %} {% hint style="warning" %} If you are using copy + paste commands, make sure to paste the impression tracking in plain text to avoid any unintended character encoding. Make sure the URL ends in `$mntn_impid=${asid}`, not `$mntn_impid=$%7basid%7d` {% endhint %} ### Conversions and Verified Visits The MNTN integration has 2 types of events: [Verified Visits](https://mountain.com/blog/how-mntn-measures-performance-without-clicks-a-deep-dive-into-the-verified-visits-model/) and Conversions. Verified Visits and conversions need to share a common identifier so that MNTN can accurately determine which conversions were preceded by a Verified Visit. By default, this identifier will be the built-in Session ID, but this value can be overridden by the `event_id` event property for custom tracking if provided and allowlisted. Verified Visits can improve conversion tracking within MNTN and are highly recommended. You can configure your events as Verified Visits and conversions in 2 ways: 1. Enable the "send page views as Verified Visits by default" setting in integration configuration. By default, this setting is already enabled. This will send all page view events as Verified Visits unless specified otherwise by the `mntn_event_type` event property. 2. Set the `mntn_event_type` property on certain events to either `visit` or `conversion`. The `mntn_event_type` property will always override the "send page views as Verified Visits by default" setting. It's recommended to set the value of `mntn_event_type` using a "send constant property" [transformation](https://documentation.freshpaint.io/admin-panel/transformations#creating-a-new-transformation) on the event definition you'd like to treat as a Verified Visit or conversion. ### Set up Test Campaign in MNTN 1. Set up a test campaign that targets a small audience 2. Attach a creative that has the Freshpaint Impression Pixel 3. Verify impressions and clicks are flowing into Freshpaint correctly by working with your Customer Success Engineer 4. Verify in Freshpaint that the events are triggering and flowing through successfully to MNTN by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging) ### Confirm events are triggering and sending to MNTN successfully To check whether MNTN is receiving events, you can go to **Reporting** in your MNTN dashboard and verify that conversions are showing and are attributable (if IP and Impression ID are allowed via the HIPAA allowlist). ## Further reading Looking for more information? See [MNTN Reference](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-reference). # MNTN Reference This is a reference document for the MNTN destination. For information on how to set up this integration, see the [MNTN Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-quick-start-guide). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Refer to this destination as **MNTN** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **MNTN::123456.** You can retrieve this value from MNTN configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## View Through Tracking Freshpaint supports view through tracking by capturing the `mntn_impid` parameter passed in by MNTN using the Freshpaint Impression Pixel. Assuming you have followed the [MNTN Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-quick-start-guide) to set up your MNTN destination, you can verify that view through tracking is working by looking for an event in event verification that contains the `$mntn_impid` field. You can also look for a transformation that shows that the event data was enriched by the Freshpaint Impression Pixel.

Transformation applying the Impression Pixel captured impression to an event

## Relevant Properties These are the properties that are sent to MNTN. If you've followed the [MNTN Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-quick-start-guide) correctly, no further action is necessary. This section is just informational.
Freshpaint propertyMNTN
parameter		TypeRequired?Description
order_idorder_idstringRecommendedUnique order identifier for connecting conversion activities to advertising campaigns.

If not provided or not allowlisted, this property will default to a unique masked ID for the conversion event.
$mntn_impidImpressionstringRecommendedThis is the MNTN View Impression ID. This property is captured by the Freshpaint Impression Pixel, and is passed to Freshpaint via the tracking pixel configured on the creative. The impression ID is required for attribution.
order_amountorder_amountnumberRecommendedThe amount associated with the conversion.
order_currencyorder_currencystringRecommendedCurrency code associated with the conversion. ISO 4217 format.
product_identifier_listproduct_identifier_listarray of stringsRecommendedList of product SKUs or identifiers associated with the conversion.
account_idaccount_idstringRecommendedAccount ID of the connected MNTN account.
event_idevent_idstringOptionalCommon identifier to connect Verified Visits to a conversion for a specific user journey.
mntn_event_typestringOptionalDetermines if an event is sent as a Verified Visit or as a conversion.

Valid values: visit, conversion
# Zeta Conversions API (Early Access) Zeta is a Connected TV (CTV) advertising platform that focuses on performance marketing. {% content-ref url="/pages/qQlV4PPdOslao70xQf1E" %} [Zeta Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/zeta-conversions-api-early-access/zeta-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/qRRcr2JmJeuIfyiPa5b3" %} [Zeta Reference](/integrations/destinations/demand-side-platforms-dsps/zeta-conversions-api-early-access/zeta-reference) {% endcontent-ref %} # Zeta Quick Start Guide This is a guide to help you get started on sending your conversion events to Zeta via Freshpaint. If you've already completed set up and are looking for more information, see [Zeta Reference](/integrations/destinations/demand-side-platforms-dsps/zeta-conversions-api-early-access/zeta-reference). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Refer to this destination as **Zeta** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **Zeta::123456.** You can retrieve this value from the Zeta configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Freshpaint Environment ID 2. Your Zeta Advertiser ID, Pixel ID, Site ID, and API Key 3. A Zeta Marketing Platform (ZMP) account mapped to your Freshpaint Environment ID (coordinated with your Zeta Account Manager) 4. \[If in HIPAA mode] Allowlist set up to allow Freshpaint to forward properties to Zeta for attribution 5. Impression pixel enabled to allow Freshpaint to do view-through conversion attribution ### To set up Zeta with Freshpaint, follow these steps: 1. **Notify your Zeta Account Manager** before activating the integration. Provide them your Freshpaint Environment ID, which can be found in your Freshpaint dashboard under "Setup". 1. Your Zeta Account Manager will create and map a ZMP account to your Environment ID. Wait for confirmation from your account team before proceeding. 2. **Make sure you have the appropriate access** in both Freshpaint and Zeta: 1. Contact your Freshpaint Account Manager to request access to this destination. Once granted, we will help you step by step through the configuration process. 3. **Create** **events in Freshpaint to track your conversions**. 4. **Enter your Zeta credentials in Freshpaint**. You will need your Advertiser ID, Pixel ID, Site ID, and API Key from your Zeta DSP account.
5. **\[If in HIPAA mode]** It is highly recommended to set the Freshpaint allowlist for Zeta to allow Freshpaint to forward `$zeta_impid` and `$zeta_userid`. These properties enable Freshpaint and Zeta to perform attribution on your conversion events.
6. **Enable the impression pixel for Zeta.** This enables Freshpaint to do view-through attribution and report the conversion event to Zeta. We recommend enabling IP matching and cookie matching, and setting the Conversion Window to at least 30 days for the best results. Then copy the Pixel Configuration URL for the next step. Click Save once you have set your preferred configuration options and copied the URL.
7. **Configure your creatives in ZMP** to include the Freshpaint impression pixel URL copied in the previous step. The URL already contains the `$zeta_impid` and `$zeta_userid` macros — Zeta will substitute the real values automatically when the ad serves. This is required for view-through conversion tracking via Freshpaint. The URL that you paste in should look like: `https://freshpaint-impression.com/pixel.png?env_id=&dest_id=&$zeta_impid={adinstanceid}&$zeta_userid={userid}` ### Verify Your Setup Once your integration is active and your creatives are running: 1. Verify in Freshpaint that the events are triggering and flowing through successfully to Zeta by using Freshpaint's [Liveview and Event Verification tools](https://documentation.freshpaint.io/admin-panel/investigate-testing-and-debugging). 2. Your Zeta account team will confirm when data is being received on their end, and will reach out if any additional data mapping is needed. # Zeta Reference This is a reference document for the Zeta destination. For information on how to set up this integration, see the [Zeta Quick Start Guide](https://documentation.freshpaint.io/integrations/destinations/demand-side-platforms-dsps/mntn/mntn-quick-start-guide). ## Destination Info * Supports [Track](/reference/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](/readme/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Supports [Freshpaint Impression Pixel](/integrations/impression-pixel) * Refer to this destination as **Zeta** in the [Integrations object](/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertiser IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **Zeta::123456.** You can retrieve this value from the Zeta configuration page for the Advertiser ID of interest. {% hint style="info" %} When no suffix is specified, all configured Advertiser IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## View Through Tracking Freshpaint supports view-through tracking by capturing the `$zeta_impid` parameter passed in by Zeta using the Freshpaint Impression Pixel. Assuming you have followed the [Zeta Quick Start Guide](/integrations/destinations/demand-side-platforms-dsps/zeta-conversions-api-early-access/zeta-quick-start-guide) to set up your Zeta destination, you can verify that view-through tracking is working by looking for an event in Event Verification that contains the `$zeta_impid` field. You can also look for a transformation that shows the event data was enriched by the Freshpaint Impression Pixel.
## Events ### Relevant Properties | Freshpaint Property | Zeta Parameter | Type | Requirement | Description | | ------------------- | -------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$zeta_userid` | `cs` | string | Required | Zeta Sizmek ID. Captured automatically by the Freshpaint Impression Pixel from the `{userid}` macro on your Zeta creatives. | | `$zeta_impid` | `impId` | string | Required | Zeta impression ID. Captured automatically by the Freshpaint Impression Pixel from the `{adinstanceid}` macro on your Zeta creatives. Required for view-through attribution. | | `email` | `em`, `es` | string | Recommended | Email address. Freshpaint automatically normalizes (lowercases, trims, removes + alias) and hashes the value as both MD5 (`em`) and SHA-256 (`es`) before sending. | | `phone` | `ph` | string | Recommended | Phone number. Freshpaint normalizes to 11-digit format with no spaces or dashes. | | `mobile_ad_id` | `mm` | string | Recommended | Mobile Ad ID. | # Direct Response Ads Direct Response ad destinations allow Advertising tools to deliver ads to targeted demographics. ## Event Mapping In additional to accepting custom events, most Direct Response Ads destinations accept a set of "standard events". These are events that have some special significant to the destination. As an example, here are some of the standard events Facebook Pixel accepts: * AddToCart * AddToWishlist * Lead * PageView * Purchase To help you get your events into a destinations standard events, Freshpaint provides event mappings. Event mappings let you rename your events before they are sent to a destination. As an example, you could map your `Submitted Email` event in Freshpaint to the Facebook Pixel standard event `lead`: ![](/files/-MCG0CBXo_nqK4e3MFkd) # AdMedia (Early Access) Send advertising conversion events directly to AdMedia {% hint style="warning" %} The AdMedia destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} {% content-ref url="/pages/YaZs8fidLUllxnKDMiPh" %} [AdMedia Quick Start Guide](/integrations/destinations/direct-response-ads/admedia-early-access/admedia-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/dCtF6YQlFcjtIWVe1TVr" %} [AdMedia Reference](/integrations/destinations/direct-response-ads/admedia-early-access/admedia-reference) {% endcontent-ref %} # AdMedia Quick Start Guide Send advertising conversion events directly to AdMedia {% hint style="warning" %} The AdMedia destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **AdMedia** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertisesr IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **AdMedia::1234123456.** You can retrieve this value from the AdMedia configuration page for the Advertiser ID of interest. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started This guide enables you to fully enable the AdMedia destination for your site. This guide assumes you have the Freshpaint snippet installed on your site — if you do not, please follow [this guide](https://documentation.freshpaint.io/readme/guides/quickstart/installing-freshpaint). ### Enable the AdMedia Integration 1. Navigate to the [Freshpaint Destinations page](https://app.freshpaint.io/destinations/catalog). 2. Search for the **AdMedia** destination. 3. Select **Configure**. 4. Enter the Advertiser ID provided by AdMedia. 5. Customers that use HIPAA mode should then configure the required and recommended properties. You can find [all properties that the AdMedia integration supports here.](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/miscrosoft-ads-conversions-api-early-access/miscrosoft-ads-conversions-api-reference) 6. Select Save. 7. Enable the AdMedia integration.
Freshpaint AdMedia integration configuration page, with Advertiser ID field selected.
### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Go to the **AdMedia** configuration page in Freshpaint. 2. Click "Configure" next to "Required Properties" and "Recommended Properties". 3. If you're using the Freshpaint/AdMedia integration for ad attribution purposes, we recommend you send the `$click_id` property. This property is required in order to see ad attribution data in AdMedia. You can do so by checking the box in the popup. 4. Next, add any other properties you'd like to send to AdMedia to the Advanced: HIPAA Allow List. Once you've followed these steps, you're ready to start sending events to AdMedia.
AdMedia integration page with recommended properties selected
## Confirm and Validate Events ### Confirm and Validate Conversions in Freshpaint 1. Navigate to your site and visit a page that should trigger your event.. 2. Trigger the event. 3. Navigate to the [Event Verification tool](https://app.freshpaint.io/event-verification). 4. Select **AdMedia** and verify your event went through. 1. This can take up to 90 seconds. 5. Verify the event is marked as `OK` or resolve any missing property issues.
AdMedia Event Verification example with OK status
# AdMedia Reference Send advertising conversion events directly to AdMedia {% hint style="warning" %} The AdMedia destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **AdMedia** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Advertisesr IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **AdMedia::1234123456.** You can retrieve this value from the AdMedia configuration page for the Advertiser ID of interest. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the AdMedia destination. For information on how to set up this integration, see the AdMedia Quick Start Guide. ## Events ### Required Properties | Freshpaint Property | AdMedia Parameter | Type | Requirement | Description | | ------------------- | ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------- | | `source` | `source` | String | Required | Source website or traffic origin. If source is not set on the event, Freshpaint falls back to `$current_url`. | | `trans_id` | `trans_id` | String | Required | Unique transaction or event identifier. If not provided, Freshpaint sends a masked event identifier. | {% hint style="warning" %} If your Freshpaint account is set up in [HIPAA Mode](https://documentation.freshpaint.io/readme/hipaa-mode), the URL will be redacted by default because it may contain PHI. For example, if the URL of the event is `https://example.com/heart-conditions#treatments?user=alice` then Freshpaint will send `https://example.com/url-redacted-by-freshpaint`. To send the complete URL to AdMedia, add the Built-in URL (`$current_url`) property to your HIPAA allowlist. {% endhint %} ### Recommended Properties | Freshpaint Property | AdMedia Parameter | Type | Requirement | Description | | ------------------- | ----------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$click_id` | `click_id` | String | Recommended | Click ID captured from the landing page URL when a visitor arrives via an AdMedia ad. Required for deterministic click-through attribution. Without this value, AdMedia records the conversion but cannot attribute it to a campaign, publisher, or placement. | | `sale_amt` | `sale_amt` | Float | Recommended | Conversion value in USD. | | `status` | `status` | String | Recommended | Conversion status. | | `status_detail` | `status_detail` | String | Recommended | Additional detail about the conversion status. | *** ### Optional Properties | Freshpaint Property | AdMedia Parameter | Type | Requirement | Description | | ------------------- | ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | `ct` | `ct` | String | Optional | Conversion type or event type (e.g. `purchase`, `lead`, `signup`). | | `$ip` | `ip` | String | Optional | The user's IP address. Blocked entirely in HIPAA Mode unless `$ip` is explicitly added to the Advanced HIPAA Allow List. | # AppLovin Event API (Early Access) Send advertising events directly to AppLovin. {% hint style="warning" %} The AppLovin Event API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} {% content-ref url="/pages/TjUydgcqFx7oyT1bqEGk" %} [AppLovin Event API Quick Start Guide](/integrations/destinations/direct-response-ads/applovin-event-api-early-access/applovin-event-api-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/0zpm0FmiWyskvRxZNIM6" %} [AppLovin Event API Reference](/integrations/destinations/direct-response-ads/applovin-event-api-early-access/applovin-event-api-reference) {% endcontent-ref %} # AppLovin Event API Quick Start Guide {% hint style="warning" %} The AppLovin Event API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Refer to this destination as **AppLovin** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started This guide enables you to fully enable the AppLovin Event API destination for your site. For simplicity the event used for demonstration purposes is the generic `Page View` event. For more complex events see[ our additional documentation](/readme/setting-up-your-events). Additionally this guide assumes you have the Freshpaint snippet installed on your site, if you do not please follow[ this guide](/readme/guides/quickstart/installing-freshpaint). 1. Find/create your **AppLovin** **Events Key** for AppLovin 2. Enable the Freshpaint AppLovin destination * If in HIPAA mode enable the required fields 3. Confirm and validate events ### Find your AppLovin Events Key for AppLovin 1. Log into your [AppLovin Ads Manager](https://ads.applovin.com/auth/signin?redirectTo=%2F). 2. Select **Events** in the left-hand menu. 3. Copy the ID at the top of the page.
AppLovin UI showing where to find AppLovin Event Key
### Enable the Freshpaint AppLovin destination 1. Navigate to the [Freshpaint Integrations page](https://app.freshpaint.io/destinations/catalog). 2. Search for the **AppLovin** integration. 3. Select **Configure** to paste your **AppLovin** **Event Key** from the above step. 4. Customers that use HIPAA mode should then configure the required, recommended, and recommended view-through properties. You can find all properties that the Freshpaint AppLovin integration supports here: [AppLovin Event API Reference](/integrations/destinations/direct-response-ads/applovin-event-api-early-access/applovin-event-api-reference). 5. Enable AppLovin. Once you've followed the steps above you can start sending events to the AppLovin Event API.
## Confirm and validate events ### Confirm and Validate Events in Freshpaint 1. Navigate to your site and visit a page that should trigger your event 2. Trigger your event (Our demonstration event is a `page_view`). 3. Navigate to the [Event Verification tool](https://app.freshpaint.io/event-verification). 4. Select **AppLovin** and verify your event went through. * This can take up to 90 seconds. 5. Verify the event is marked as `OK` or resolve missing property issues.
### Confirm and Validate Events in AppLovin When first setting up your AppLovin account, you will be required to send 1 of each required event before you can view the Event Manager. You can view the list of required parameters for each of these events types[ in their documentation](https://support.axon.ai/en/growth/promoting-your-websites/axon-pixel-integration/events-and-objects).
Afterwards, to check whether AppLovin is receiving events: 1. Log into your [AppLovin Ads Manager](https://ads.applovin.com/auth/signin?redirectTo=%2F). 2. Select **Events** in the left-hand menu. 3. You should see events coming through under the large graph under **Event details** on this page. 1. Successfully sent events will increment the Count and the "Last seen" time. It's usually within a few seconds. They mention at the top of the page it can be up to 2 hours. 4. See that your event has a status of :green\_circle: **All Working**. Click to spot check events.
# AppLovin Event API Reference {% hint style="warning" %} The AppLovin Event API destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Refer to this destination as **AppLovin** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the AppLovin destination. For information on how to set up this integration, see the [AppLovin Event API Quick Start Guide](/integrations/destinations/direct-response-ads/applovin-event-api-early-access/applovin-event-api-quick-start-guide). ## Events When you send an event to the AppLovin Event API destination from Freshpaint, Freshpaint will create an event in the AppLovin event manager by hitting AppLovin's API. ### Event Properties
Freshpaint propertyAppLovin parameterTypeRequirementDescription
$aleidaleidstringRequiredThe clickID of the event, from the ?aleid query parameter.
applovin_event_namenamestringRequired

The AppLovin event name to track. *See below Events Reference for all values.

Note: If this property is absent, Freshpaint will attempt to use the name of the Freshpaint event. This will only work if the Freshpaint event name is one of the specific supported AppLovin names, so we recommend sending event name separately.

$timeevent_timenumberRequiredThe current Unix epoch time in milliseconds.

Freshpaint will autofill this value if missing.
dedupe_iddedupe_idstringRequiredUnique identifier for the event, used for deduplication.

Freshpaint will autofill this value if dedupe_id is not explicitly provided.
event_source_urlevent_source_urlstringRequiredThe URL where the event occurred, must start with "http://" or "https://".

Freshpaint will use the Freshpaint SDK's built in $current_url with the full URL redacted if event_source_url is not provided.
$ipclient_ip_addressstringRequiredThe IP address of the user from the browser where the event was performed.

Freshpaint will use the Freshpaint SDK's built in $ip value from the browser event.
### Events Reference The AppLovin / Axon Event API has a number of specific event types and corresponding values required for each of those event types. You can view the [full list of details in their documentation](https://support.axon.ai/en/growth/promoting-your-websites/axon-pixel-integration/events-and-objects). **Valid Event Names:** * add\_to\_cart * add\_payment\_info * begin\_checkout * generate\_lead * login * purchase * page\_view * remove\_from\_cart * search * sign\_up * subscribe * view\_cart * view\_item **Required event fields** Many of the events have required fields if that type of event is sent. For example: 1. `items` must be provided for `view_item`, `add_to_cart`, `begin_checkout`, and `remove_from_cart`. 2. `value` must be provided for `begin_checkout` and `purchase` 3. `currency`, `shipping` , `tax` , and `transaction_id` are also required for `purchase` events. 4. `searchTerm` must be provided for `search` **Example** An example set of these properties might look like: ```json { "currency": "USD", "items": [ {"item_id": "abc-123", "item_category_id": 111} ], "value": 1200 } ``` ### User Data Properties When you send events to AppLovin they will attempt to match those actions to a particular user in AppLovin. {% hint style="warning" %} Note: although listed as Recommended, **at least one of the following user properties is required by AppLovin:** `client_id`, `axwrt`, and `alart`. {% endhint %}
Freshpaint propertyAppLovin parameterTypeRequirementDescription
$device_idclient_idstringRecommended*

A stable first-party identifier that should be unique to the user.

Freshpaint provides this value with from a cookie set by the Freshpaint SDK.

axwrtaxwrtstringOptionalA custom value typically set by the Axon native Pixel.

This is not needed with Freshpaint as long as the $device_id is used, which is provided by default with the Freshpaint SDK.
alartalartstringOptionalA custom value typically set by the Axon native Pixel.

This is not needed with Freshpaint as long as the $device_id is used, which is provided by default with the Freshpaint SDK.
$user_agentclient_user_agentstringOptionalThe user agent of the browser.
$session_idsession_idstringOptionalThe ID of the user session.
esiesistringOptionalSource of event. app or web.

Freshpaint will default this to web.
ifaifastringOptionalThe user’s identifier for advertisers. idfa or gaid
idfvidfvstringOptionalThe user’s identifier for vendors
ososstringOptionalThe user’s operating system: ios, android, or desktop_os.
# Bing Insights The Bing Insights destination allows Freshpaint to pull campaign performance data (spend, clicks, conversions) from your Bing ad account to power the Ad Performance and Insights Overview dashboard. This destination provides visibility into how your Bing advertising spend drives appointments and revenue. {% hint style="info" %} This destination pulls data *from* Bing—it does not send events to Bing. If you need to send conversion events to Bing, use the Microsoft Ads Conversions API destination instead. {% endhint %} # Bing Insights Quick Start Guide ### Prerequisites Before you begin, ensure you have the following: 1. Microsoft Advertising account with active ad campaigns 2. Add the service principal of Microsoft Advertising API Service to your organization. Use an account with Global Administrator or Cloud App Administrator permissions. 3. Developer Token - The person authenticating must have access to a Developer Token in the Microsoft Ads dashboard. Without this, the integration cannot access campaign data. 4. Manager Account ID and Account ID - You'll need both your top-level customer (manager) account ID and the specific ad account ID you want to connect. 5. Active ad campaigns - The integration pulls data from your running or completed campaigns {% hint style="info" %} Note for agency-managed accounts: If your Microsoft Ads account is managed by an agency, you may need to coordinate with them to grant appropriate access before authenticating. {% endhint %} ### Getting Started 1. Get Your Ad Account IDs * Navigate to [https://ads.microsoft.com](https://ads.microsoft.com/) and sign in * Click on "Settings" * Your Account ID can be found under "Account Settings" * Your Manager Account ID can be found under "Manager account settings" 2. Get Your Developer Tokens * In Microsoft Ads, go to Settings > Developer Settings * Copy your Developer Token 3. Create the Bing Insights Destination in Freshpaint * In Freshpaint, navigate to your [Destinations page](https://app.freshpaint.io/destinations/catalog?category=overview) and search for Bing Insights * Enter your Developer Token, Account ID, and Manager Account ID 4. Click "Connect with Microsoft" 5. Enable Destination * Click on the "Enable" button at the top of the configuration settings ### Configuring Attribution Parameters The Insights Attribution page shows performance for each individual Microsoft Advertising campaign. This breakdown relies on two inputs: campaign spend, which Freshpaint pulls automatically from the Microsoft Advertising API, and a mapping between each ad click and the campaign it came from. Microsoft Advertising does not expose that click-to-campaign mapping through its API, so a tracking template adds the campaign ID to each ad click URL instead. Once the tracking template is live, Freshpaint reads the campaign ID from the `mscid` parameter on each incoming click and attributes the click to that campaign automatically. #### 1. Open the account-level tracking template This setup uses a Microsoft Advertising tracking template, which can be set at the account level. In Microsoft Advertising, go to **Campaigns → Settings → Account level options → Tracking template**. Microsoft recommends setting the tracking template at the account level so it applies to every campaign in the account, including campaigns added later. For Microsoft's full list of tracking parameters, see [Microsoft Advertising: URL tracking with upgraded URLs](https://learn.microsoft.com/en-us/advertising/guides/url-tracking-upgraded-urls). #### 2. Set the tracking template value For an account with no existing tracking template, set the value to: ``` {lpurl}?mscid={CampaignID} ``` For an account that already has a tracking template, append the parameter to the end of the current value instead: ``` &mscid={CampaignID} ``` `{lpurl}` is a required Microsoft placeholder for the landing page URL. `{CampaignID}` is a Microsoft Advertising parameter that Microsoft replaces with the campaign's ID each time an ad is clicked. `mscid` is the parameter key Freshpaint reads, so enter it exactly as shown. {% hint style="warning" %} **Configure every active campaign.** Freshpaint pulls spend for all campaigns from the Microsoft Advertising API, but a click only maps to a campaign when that campaign's URLs carry `mscid={CampaignID}`. When some campaigns are missing it, their cost per acquisition (CPA) appears inflated, because Freshpaint counts the spend for those campaigns but cannot match their conversions. Setting the tracking template at the account level is the most reliable way to cover every campaign. {% endhint %} {% hint style="info" %} **Data starts at setup - not retroactively.** Campaign breakdown data starts populating only after this setup is complete. Clicks that happened before the parameter was in place are not attributed to a campaign. {% endhint %} #### 3. Verify campaign breakdown in Insights After the tracking template is live and new clicks have arrived, open the **Attribution page** in Insights and expand the Microsoft Advertising (Bing) source. Clicks that Freshpaint cannot match to a campaign appear under an `UNKNOWN` row. A large or growing `UNKNOWN` row could mean one or more campaigns are still missing the `mscid={CampaignID}` parameter. {% hint style="success" %} **Success:** Individual campaign names appear in the campaign breakdown, and the `UNKNOWN` row stays small relative to total volume. {% endhint %} ### Best Practices & Reminders **Set the tracking template at the account level** Adding `fp_insights_cid={CampaignID}` once at the account level covers every current campaign and any campaign created later. Reserve per-campaign overrides for campaigns that genuinely need different URL options. **Monitor the `UNKNOWN` row** Check the `UNKNOWN` campaign row in the campaign breakdown periodically. Growth in that row usually means a new campaign shipped without the parameter. Add the parameter to that campaign to restore accurate attribution going forward. **No Retroactive Data** Campaign breakdown reflects clicks captured after setup only. Note the date the parameter went live so campaign-level numbers are read in the correct time context. **Coordinate with the agency for managed accounts** For agency-managed Microsoft Advertising accounts, have the agency add the parameter to the account URL options, since that team controls campaign configuration. ### What's Next? * **Configure other ad platforms** — Freshpaint uses the same campaign-ID pattern across ad platforms. Set up the [Google Ads campaign ID parameter](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide#add-the-campaign-id-to-your-final-url-suffix) and the [Meta Insights URL parameters](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/meta-insights/meta-insights-quick-start-guide#required-url-parameters) to enable campaign breakdown for those platforms. * **Review campaign performance in Insights** — Open Bing Insights, select **Group By Campaigns**, and compare spend and conversions across campaigns to guide budget decisions. * **Monitor attribution health** — Keep the `UNKNOWN` campaign row small by confirming every new campaign inherits the `fp_insights_cid={CampaignID}` parameter. # Everflow (Early Access) Send conversion events directly to Everflow. {% hint style="warning" %} The Everflow destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} {% content-ref url="/pages/qxIxfI4rh1QXO4XSoe04" %} [Everflow Quick Start Guide](/integrations/destinations/direct-response-ads/everflow-early-access/everflow-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/hRR8KqRZH3FQrOx49V5M" %} [Everflow Reference](/integrations/destinations/direct-response-ads/everflow-early-access/everflow-reference) {% endcontent-ref %} # Everflow Quick Start Guide Send conversion events directly to Everflow. {% hint style="warning" %} The Everflow destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Everflow** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Tag IDs, you can choose a specific one by suffixing the Advertiser ID, such as: **Everflow::1.** You can retrieve this value from the Everflow configuration page. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started This guide enables you to fully enable the Everflow destination for your site. This guide assumes you have the Freshpaint snippet installed on your site — if you do not, please follow [this guide](https://documentation.freshpaint.io/readme/guides/quickstart/installing-freshpaint). ### Locate the Network ID, Advertiser ID and Tracking Domain in Everflow 1. Log in to the Everflow platform. 2. Copy the Network ID - this is the unique identifier for the Everflow network account. 3. Copy the Advertiser ID. 4. Navigate to the tracking domain settings and copy the Tracking Domain URL. ### Enable the Freshpaint Everflow destination 1. Navigate to the [Freshpaint Destinations page](https://app.freshpaint.io/destinations/catalog). 2. Search for the **Everflow** destination. 3. Select **Configure** to paste your Network ID, Advertiser ID and tracking domain from the above steps. 4. Customers that use HIPAA mode should then configure the required, recommended, and recommended view-through properties. You can find [all properties that the Freshpaint Everflow integration supports here](/integrations/destinations/direct-response-ads/everflow-early-access/everflow-reference). 5. Enable Everflow. Once you've followed the steps above you can start sending events to Everflow. ### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Go to the Everflow configuration page in Freshpaint. 2. Click "Configure" next to "Recommended Properties". 3. If you're using the Freshpaint/Everflow integration for ad attribution purposes, we recommend you send the `$ef_transaction_id` property. This property is required in order to see ad attribution data in Everflow. You can do so by checking the `$ef_transaction_id` box in the popup. 4. If you want to track attribution tied to coupon codes, you'll need to send the `coupon` property. Similarly, you should send `value` to track the revenue partners generate.
Freshpaint Everflow destination showing Required Properties
Once you've followed these steps, you're ready to start sending events to Everflow! ## **Confirm and Validate Events** ### **Confirm and Validate Conversions in Freshpaint** 1. Navigate to your site and visit a page that should trigger your event. 2. Trigger your event. 3. Navigate to the [Event Verification tool](https://app.freshpaint.io/event-verification). 4. Select **Everflow** and verify your event went through. * This can take up to 90 seconds. 5. Verify the event is marked as `OK` or resolve any missing property issues.
Freshpaint test event showing OK status
# Everflow Reference Send conversion events directly to Everflow. {% hint style="warning" %} The Everflow destination is currently in Early Access. Please contact for more information about this integration. {% endhint %} ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Everflow** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Tag IDs, you can choose a specific one by suffixing the Network ID, such as: **Everflow::1234123456.** You can retrieve this value from the Everflow configuration page for the Network ID of interest. * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the Everflow destination. For information on how to set up this integration, see the [Everflow Quick Start Guide](/integrations/destinations/direct-response-ads/everflow-early-access/everflow-quick-start-guide). ## Events ### Required Properties | Freshpaint Property | Everflow Parameter | Type | Requirement | Description | | -------------------- | ------------------ | ------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$ef_transaction_id` | `transaction_id` | string | At least one of `$ef_transaction_id` and `coupon` is required. | The Everflow transaction ID (click ID) captured automatically from the landing page URL or through the Everflow transaction ID cookie. Required for click-through attribution. | | `coupon` | `coupon_code` | string | At least one of `$ef_transaction_id` and `coupon` is required. | The coupon code tied to the partner. We do not automatically capture this value like how we capture the transaction ID. The coupon code should be sent within a track event when the order is placed. | | `$ip` | `user_ip` | string | Recommended | The IP of the user. | | `$user_agent` | `user_agent` | string | Recommended | The user agent of the user. | ## Troubleshooting **Conversion events not showing up in Everflow**: For an event to show up as a conversion event it must have a `$ef_transaction_id` or `coupon` property. You can validate that events going to Everflow have at least one of these properties using the [Freshpaint Liveview](https://documentation.freshpaint.io/events/liveview). **Events show "Missing Required Property" in Event Verification**: The `$ef_transaction_id` and `coupon` properties were absent when the event was processed. If it's occurring on events that should have the transaction ID, check that the Freshpaint snippet is installed on the landing page and that `$ef_transaction_id` isn't being stripped by redirects or link-shorteners before the visitor lands. **The Tracking Domain URL is rejected during configuration**: The Tracking Domain must begin with `http://` or `https://`. Bare domains without a scheme (e.g. `tracking.example.com`) are not accepted. # Facebook Conversions API The Facebook Conversions API allows advertisers to send events directly to Facebook via a server-side connection. Server-side events are sent to Facebook via the Facebook Conversions API (formerly known as Facebook Server-Side API). The Facebook Conversions API enables you to measure events that may not happen in the browser, improve accuracy by tracking events both in the browser and on the server, and more. {% content-ref url="/pages/u9E5DYpvFdZa1ilDOslU" %} [Facebook Conversions API Quick Start Guide](/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/OLNHBEf4SjkJxvTPSIia" %} [Facebook Conversions API Reference](/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference) {% endcontent-ref %} # Facebook Conversions API Quick Start Guide The Facebook Conversions API allows advertisers to send events directly to Facebook via a server-side connection. Server-side events are sent to Facebook via the Facebook Conversions API (formerly known as Facebook Server-Side API). The Facebook Conversions API enables you to measure events that may not happen in the browser, improve accuracy by tracking events both in the browser and on the server, and more. ## Destination Info * Accepts [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Facebook Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Facebook Conversions API::0123456789012345.** You can retrieve this value from the Facebook Conversions API configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Facebook Pixel ID and Access Token 2. Conversion events configured in your Freshpaint account 3. The [Freshpaint Autotrack script tag](https://app.freshpaint.io/sources) installed on your site ### To set up the Facebook Conversions API with Freshpaint, first follow these steps: 1. Go to the Facebook Conversions API [configuration page](https://app.freshpaint.io/destinations/apps/facebook-conversions-api) in Freshpaint and click "Configure". 2. In Facebook, go to Events Manager > Data Sources and find your Pixel ID and copy this value into your Freshpaint Facebook Conversions API destination:
3. To use the Facebook Conversions API, you'll need to generate an access token. Copy this value into your Freshpaint Facebook Conversions API destination:
You have successfully set up the Facebook Conversions API destination in Freshpaint! {% hint style="info" %} If you are using this integration to map Freshpaint events to Facebook Standard Events, see the Reference Guide [here](/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference#standard-facebook-events) for more details. {% endhint %} {% hint style="warning" %} Healthcare companies may be restricted from using lower-funnel Standard Events due to recent Meta changes. We recommend using custom events with generic naming (e.g., "Event1", "Event2"). See the [Custom Events](https://documentation.freshpaint.io/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference#custom-facebook-events) section for details. {% endhint %} ### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Go to the Facebook Conversions API [configuration page](https://app.freshpaint.io/destinations/apps/facebook-conversions-api) in Freshpaint. 2. You should see a message indicating that required properties are not allowed. Click "Configure" next to "Required Properties".

Configuring required properties for Facebook Conversions API

3. Facebook requires that you send the User Agent from the browser where the event was performed for each event. After your organization's legal/compliance team approves this, check the box next to "User Agent" and click "Confirm".
4. Returning to the Facebook Conversions API configuration page, click "Configure" next to "Recommended Properties".
5. Freshpaint recommends sending the following additional properties to facebook. After your organization's legal/compliance team approves this, check the box next to "$fbclid", and the box next to "action\_source", and click "Confirm".\ \ $fbclid: When a user clicks on your ad on Facebook, the url sometimes includes a fbclid query parameter. Freshpaint captures this click ID from the url and sends the value as the Facebook Ad Click ID to help improve ad matching scores.
Allow Freshpaint to send the facebook click id, action source, facebook browser id, and facebook event name to Facebook

Allow Freshpaint to send the facebook click id, action source, facebook browser id, and facebook event name to Facebook

1. You've now allowed all the basic properties for Facebook Conversions API. Your destination should now look like this:
{% hint style="info" %} With HIPAA Mode enabled, the url value will be redacted by default because it may contain PHI. For example, if the URL of the event is then Freshpaint will send {% endhint %} {% hint style="warning" %} If you add the Built-in `Url` to your allowlist, the url will not be redacted. {% endhint %} ### That's it! Now all you need to do to send an event to Facebook Conversions API is enable the destination on your Freshpaint event definitions:
Navigate to your Freshpaint event, and toggle the destination on to enable the event to be sent to the Facebook destination. If you've configured multiple Facebook pixels, you'll need to toggle each pixel individually for each Freshpaint event.
If you're using Google Tag Manager to send data to Facebook, and you have multiple pixel IDs enabled, you'll need to specify which pixel ID(s) you'd like to enable the event for in the event tag.
### Confirm and validate conversions in Events Manager To make sure that Freshpaint is connected to your Facebook Pixel, navigate to your Events Manager.
{% hint style="info" %} Events may take a few minutes to appear in your Facebook Events manager overview. {% endhint %} # Facebook Conversions API Reference ## Destination Info * Accepts [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Facebook Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **Facebook Conversions API::0123456789012345.** You can retrieve this value from the Facebook Conversions API configuration page for the Pixel ID of interest. {% hint style="info" %} When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the Facebook Conversions API destination. For information on how to set up this integration, see the[ Quick Start guide](/integrations/destinations/direct-response-ads/facebook-conversions-api/facebook-conversions-api-reference). ## Events When you send an event to Facebook from Freshpaint, Freshpaint will create an event in Facebook by hitting Facebook's [event API](https://developers.facebook.com/docs/graph-api) endpoint at:[ ](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[https://graph.facebook.com/{API\_VERSION}/{PIXEL\_ID}/events?access\_token={TOKEN}](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN})[.](https://graph.facebook.com/%7BAPI_VERSION%7D/%7BPIXEL_ID%7D/events?access_token={TOKEN}) ### Standard Facebook Events See below for a complete list of Facebook standard events, the Freshpaint event definitions they are mapped to, and the available properties that can be sent in with each event. All properties are optional unless otherwise noted as "Required". | Facebook Event | Freshpaint Event Definition | Available Facebook Properties | | ---------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `AddToCart` | AddToCart | `content_ids`, `content_name`, `content_type`, `contents`, `currency`, `value` | | | product added | | | | added product | | | `AddToWishlist` | AddToWishlist | `content_name`, `content_category`, `content_ids`, `contents`, `currency`, `value` | | `AddPaymentInfo` | AddPaymentInfo | `content_category`, `content_ids`, `contents`, `currency`, `value` | | `CustomizeProduct` | CustomizeProduct | \`\` | | `Contact` | Contact | | | `CompleteRegistration` | CompleteRegistration | `content_name`, `currency`, `status`, `value` | | `Donate` | Donate | | | `InitiateCheckout` | InitiateCheckout | `content_category`, `content_ids`, `contents`, `currency`, `num_items`, `value` | | | checkout started | | | | started checkout | | | `Lead` | Lead | `content_category`, `content_name`, `currency`, `value` | | `Purchase` | Purchase |

Required: value, currency
Optional: content\_ids, content\_name, content\_type, contents, num\_items

| | | | | | `Schedule` | Schedule | | | `Search` | Search | `content_category`, `content_ids`, `contents`, `currency`, `search_string`, `value` | | | products searched | | | | searched products | | | `StartTrial` | StartTrial | `value, currency, predicted_ltv` | | `SubmitApplication` | SubmitApplication | | | `Subscribe` | Subscribe | `value, currency, predicted_ltv` | | `ViewContent` | ViewContent | `content_ids`, `content_category`, `content_name`, `content_type`, `contents`, `currency`, `value` | | | product list viewed | | | | viewed product list | | | | product category viewed | | | | viewed product category | | | | product viewed | | | | viewed product | | {% hint style="info" %} Facebook Events are case-sensitive {% endhint %} Any of the space-delimited names above are case-insensitive and may be alternatively delimited by an underscore or no separation. For example, "product added" can also be expressed as: * Product\_added * productAdded These non-Facebook-specific names can be useful when sending to multiple destinations, such as **Facebook Conversion API** and **TikTok Ads**, without requiring a Rename Transformation for one or both destinations. ### Custom Facebook Events {% hint style="warning" %} Due to recent Meta changes, healthcare companies may be restricted from using lower-funnel Standard Events such as "Schedule" or "Add to Cart". Freshpaint recommends sending custom events with generic naming that excludes any health information. {% endhint %} #### Steps 1. Create an event in Freshpaint or GTM, using the Freshpaint template. 2. Use a generic name, excluding health context (ex: Event1). You can also do this by adding a Rename Transformation in Freshpaint.
3. Accept the custom event(s) in Events Manager > Overview. After creating custom events, you'll need to review and confirm them in [Meta Events Manager](https://www.facebook.com/business/help/642275438032995). Review and select events. 4. These events should now show up in your Data Sources view. ### Required Server Event Parameters Parameters are JSON-formatted objects that you can include when tracking standard and custom events. They allow you to provide additional information about your users and their actions. #### Event Source URL {% hint style="warning" %} If your Freshpaint account is set up in [HIPAA Mode](/readme/hipaa-mode), the URL will be redacted by default because it may contain PHI. For example, if the URL of the event is `https://example.com/heart-conditions#treatments?user=alice` then Freshpaint will send `https://example.com/url-redacted-by-freshpaint`. To send the complete URL to facebook, add the Built-in `URL` (`$current_url) property` to your HIPAA allowlist. {% endhint %} #### Action Source {% hint style="warning" %} Facebook requires every event sent to the Conversions API to have an `action_source` parameter describing where the event came from. If `action_source` is "website" (the default value), then the Built-in User Agent`($user_agent) / user_agent` is required to be Allowlisted, if in HIPAA mode. The URL must also be sent in some form - as noted above, Freshpaint will always send a value for URL. These correspond to the `client_user_agent` and `event_source_url` properties described in [facebook's documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/best-practices/#req-rec-params). {% endhint %} `action_source` is set to "website" by default for server-side events. `action_source` should be included under `properties` on track events. | Action source value | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `website` | Conversion was made on your website. | | `app` | Conversion was made on an application(Android, iOS, Windows). See Facebook conversions app data [documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/app-data/). | | `email` | Conversion happened over email. | | `phone_call` | Conversion was made over the phone. | | `chat` | Conversion was made via a messaging app, SMS, or online messaging feature. | | `physical_store` | Conversion was made in person at your physical store. | | `system_generated` | Conversion happened automatically, for example, a subscription renewal that’s set on auto-pay each month. | | `other` | Conversion happened in a way that is not listed. | #### Client User Agent `client_user_agent` is automatically set from the built-in `$user_agent` property, or by including the `user_agent` property on track events. The value should be the user agent of the browser where the event occurred. #### ### Additional Parameters When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. In most cases, you'll want to send additional user traits and [Facebook parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) to improve the number of the events that are matched to a Facebook user. See [Facebook's documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters) on all of the parameters that Facebook Conversions API accepts. The Freshpaint integration also supports the values seen in [conversion app data parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/app-data/). #### User Traits User traits you can include as event properties to improve match rate include: * `email` * `phone` * `last_name` * `first_name` * `ip_address`(is automatically set from built-in `$ip` property, or from `ip_address` property) * `user_agent` * `state` * `city` * `zip` * `country` * `dob` * `gender` Facebook requires the following [customer info parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters/) to be hashed: * `email` * `phone` * `last_name` * `first_name` * `state` * `city` * `zip` * `country` * `dob` * `gender` Freshpaint will automatically hash the values sent with any of these properties when sending them to Facebook. Read [Facebook's documentation](https://www.facebook.com/business/help/765081237991954) on how match quality for events helps deliver ads to people who are more likely to take the action you care about, and attribute those actions back to your ads. #### Facebook's fbp and fbc Parameters {% hint style="warning" %} You should ensure the`fbc`parameter, at minimum, is sent whenever possible. {% endhint %} The `fbc` parameter is automatically derived and sent by Freshpaint when the `fbclid` query parameter is available (captured by Freshpaint as `$fbclid`). If in HIPAA mode, you must have the Recommended property `$fbclid` Allowlisted for this to work. You may explicitly send `fbc` if desired, in which case it will be sent, overriding the `$fbclid`-derived value if any (provided that it's Allowlisted, if in HIPAA mode). The `fbp` parameter is automatically generated and sent by Freshpaint. This generated value can be overridden if you send the value with the event (Allowlisting applies here in HIPAA mode). See [Facebook's documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc) for more information. ## Configuration Options ### Transformations #### Converting Freshpaint Events Into Facebook Standard Events Freshpaint events can be converted into one of Facebook's [standard events](https://developers.facebook.com/docs/meta-pixel/reference#standard-events). A popular use case would be to convert an existing conversion event into Facebook's Purchase event. The Conversions API creates a connection between your first-party customer data and the Meta systems that optimize ad targeting and help measure the results of your advertising efforts. In the example below, we are going to transform an existing "Test Event" into one of Facebook's standard Purchase events. To get started, create a new [Transformation](https://app.freshpaint.io/transformations/new) and select [Standard Event](https://app.freshpaint.io/transformations/new/standard-event). Next, select the existing Freshpaint event you want to transform and the destination you want to send it to:
Then, select the "Purchase" event from the list of standard mappings and click "Save" to go to the following step:
{% hint style="info" %} Some of Facebook's [standard events](https://developers.facebook.com/docs/meta-pixel/reference#standard-events) requires a certain set of properties. {% endhint %} In the case of the Purchase event, your existing Freshpaint event will need the following event properties: * `value` (amount of the conversion) * `currency` (USD, CAD, etc) In the case of the InitiateCheckout event, your existing Freshpaint event will also need the following event property: * num\_items (number of items) For this transformation, you'll see that the event will be sent to Facebook named as "Purchase" while converting the `value` property type into a number and sending the `currency` property value in all uppercase characters as required by Facebook.
If a `currency` property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send `USD` as a constant property for your conversion event: As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events. If a `currency` property isn't sent with your conversion event and all of your conversions are in a single currency type such as USD, you can add a new transformation rule to send `USD` as a constant property for your conversion event: As new instances of "Test Event" occur, the transformation would then send them to the Facebook Conversions API destination as standard Purchase events. Finally, visit your [Facebook Events Manager account](https://business.facebook.com/events_manager2/list) and navigate to the Overview tab and confirm the Purchase event is in the list:
{% hint style="info" %} Note: events may take a few minutes to populate in this view. {% endhint %} ## Options for Configuring Facebook Destinations There are a few different ways to implement conversion tracking with Freshpaint's Facebook Conversions API integration. You can use it to complement tracking with your [Facebook Pixel](/integrations/destinations/apps/facebook-pixel), or you can use it as a standalone integration. The option that's best for you depends on your specific goals with the Facebook Conversions API. {% hint style="info" %} If you are a HIPAA customer, you should use only Facebook Conversions API {% endhint %} ### Use Only Facebook Conversions API This approach is best if you don't want to load the Facebook Pixel on your site, or if you want more control over what gets sent to Facebook. {% hint style="info" %} HIPAA customers should use this approach to remain HIPAA complaint {% endhint %} #### Matching When you send user actions to Facebook, Facebook will attempt to match those actions to a particular Facebook user. When using just the Facebook Conversions API without including many properties normally collected in the browser, the match rate will likely be lower than if they were included. The match rate can be improved by including [additional parameters](#additional-parameters). #### Deduplication In this approach, events are only sent from the server, so no deduplication is necessary. ## Validation To validate that your events are making it to Facebook, you can use Facebook's `test_event_code` property. To set up a test event code, see: .
Then, you can send the test event code from your browser console like so: * `freshpaint.track("Test Event", {test_event_code: 'TEST60659'})` OR * `freshpaint.addEventProperties({test_event_code: 'TEST60659'})` ## View-Through Conversions and Retargeting View-through conversions and retargeting are possible for a user when the [user traits provided](https://documentation.freshpaint.io/integrations/destinations/advertising-destinations/facebook-conversions-api/facebook-conversions-api-reference#additional-parameters), such as email or IP address, match a user in Facebook. If user traits are not provided, then view-through conversions and retargeting are not possible. # Google Ads Conversion API {% hint style="info" %} The Google Ads Conversion API requires setting up new Conversion Actions within Google Ads. If you want to re-use your existing Google Ads configuration, take a look at the [server-side mode of the Google Ads destination](https://documentation.freshpaint.io/integrations/destinations/advertising-destinations/google-ads/google-ads-reference#server-side). {% endhint %} {% hint style="info" %} For [Insights](https://documentation.freshpaint.io/admin-panel/insights): You must enable the Google Ads API in your Google Cloud account before Freshpaint can pull spend and campaign data. If you don't have a Google Cloud account set up, you'll need to create one and enable the API. Contact your Google Ads administrator or IT team if you need assistance. {% endhint %} Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. {% content-ref url="/pages/Fk257Ri7xpzniwL396cO" %} [Google Ads Conversion API Quick Start Guide](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/eaBrwXFi2W4sXqt112cS" %} [Google Ads Conversions API Reference](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversions-api-reference) {% endcontent-ref %} # Google Ads Conversion API Quick Start Guide {% hint style="info" %} The Google Ads Conversion API requires setting up new Conversion Actions within Google Ads. If you want to re-use your existing Google Ads configuration, take a look at the [Google Ads Proxy Destination](/integrations/destinations/direct-response-ads/google-ads). {% endhint %} {% hint style="info" %} For [Insights](https://documentation.freshpaint.io/admin-panel/insights): You must enable the Google Ads API in your Google Cloud account before Freshpaint can pull spend and campaign data. If you don't have a Google Cloud account set up, you'll need to create one and enable the API. Contact your Google Ads administrator or IT team if you need assistance. {% endhint %} Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Refer to this destination as **Google Ads Conversion API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started ### What You'll Need 1. Your Google Ads Customer ID 2. [Conversion Actions](https://support.google.com/google-ads/answer/12216226?hl=en) configured in your Google Ads account 3. Conversion Events configured in your Freshpaint account ### To set up Google Ads Conversions API with Freshpaint, first follow these steps: 1. Find your customer-id in your [Google Ads account](https://ads.google.com/aw/overview). The Customer ID will be shown when logged into your Google Ads account above you email address. It should look similar to 123-123-1234.\ ![](/files/7vzEnMm46vaI4lmDCZOG) 2. Go to the [Google Ads Conversion API configuration page](https://app.freshpaint.io/destinations/apps/google-ads-conversion-api) in Freshpaint. 3. Configure the Customer ID within Freshpaint.\ ![](/files/Z266EkKc1e9GUlJwx4Ew) 4. Use the `Connect with Google Ads` button to grant Freshpaint access to your Google Ads account.\ ![](/files/MXQd3oGajL3fIJS9wQ2d) 5. Select `User Account` and then click `Connect with Google CM360` as the method to connect Freshpaint to Google Ads 6. Select the user you want Freshpaint to use when sending events to Google Ads. This user requires `Admin` access level within Google Ads.\ ![](/files/RphMEkJ5fThZD1GpdFP0) 7. Grant access to Freshpaint by selecting `Continue`.\ ![](/files/QakLbWAdS28zDmwYfMmU) 8. The [Google Ads Conversion API configuration page](https://app.freshpaint.io/destinations/apps/google-ads-conversion-api) should now show the Access Permission as connected.\ ![](/files/0DSdw19cMVUw65DwkpoI) ### Next, you'll need to setup Conversion Actions in Google Ads When using the conversion API to send conversions to Google Ads, you will need to create new `import` conversion actions. 1. In your Google Ads account go to `Goals > Summary`. Scroll down and click on the `+ Create Conversion Action` button to create a new conversion action.
2. Select `Import`\ ![](/files/iQayMVGJuIP0lwZJ9zHI) 3. Select `CRMs, files, or other data sources` and `Track conversions from clicks`, and then `Continue` to the next page.\ ![](/files/Y867y7OG6rdFz6CiAa9R) 4. In the `Data source` section, select `Skip this step and set up a data source later`.![](/files/yZELC4A0BxojIFay1fB8) 5. Configure your conversion action within Google Ads. This configuration is the same as any other action in Google Ads. Choose any conversion goal that makes sense for your organization.
7. Click `Add` and then `Save and continue`. 8. On the next page, scroll down, skip the section on setting up data sources, and click `Done` .
### Finally, link your Freshpaint Event to your Google Ads Action 1. In your Freshpaint account, click on `Transformations` in the sidebar navigation.
2. Click on the `Create new` button to create a new transformation.
3. Select `Modify Data` transformation type.
4. Select the Freshpaint event you want to send as the conversion. Then select `Google Ads Conversion API` for the destination. Finally, click `Save & Add Transformations`.
5. On the next page, select `Send Constant Property` in the `Add new transformation` dropdown options.
6. Fill in `ctname` for `Property Name` . `Property Value` should be the Google Ads Conversion Name of the conversion you created in the previous section. Select `Text` for `Constant Type`.
7. Click "Save" to save the transformation for the event. You've now linked your Freshpaint event to your Google Ads Conversion Action.
{% hint style="info" %} Conversions may take up to 24 hours to appear in your Google Ads Conversion Goals. {% endhint %} ### Required Properties {% hint style="info" %} The following event properties are **required** in order to attribute events to specific ads. {% endhint %}
Freshpaint propertyGoogle Ads parameterTypeDescription
$gclid or $gbraid or $wbraidgclid or wbraid or gbraidstringgclid (Google Click ID) is generated at ad click time and appended to the landing page URL. Freshpaint will automatically capture gclid for events from your website. If you wish, you may provide $gclid as an event property to override the automatically captured value. wbraid or gbraid can be used instead of gclid.
ctname or ctidctidstringThe Conversion Name or Conversion Id of the conversion action in Google Ads. When using the Conversion Name, the Freshpaint integration will lookup the Conversion Id before sending the event to Google. The name of the Freshpaint Event must exactly match the name of the Google Ads Conversion name.
{% hint style="info" %} Freshpaint will only deliver events to Google when a user arrives on your site by clicking on a Google Ad, thus generating an `gclid`. Without `gclid`, Google will not be able to attribute conversions. {% endhint %} There are other optional parameters you can add to your events in order to achieve different use cases. You can view the full list of parameters [here](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversions-api-reference#server-side). ### Add the Campaign ID to your Final URL Suffix To ensure visits with `$gbraid`or `$wbraid`are attributed to the correct campaign, add the Campaign ID to your [Final URLs](https://support.google.com/google-ads/answer/9054021?hl=en). This can be configured globally or at the campaign, ad group, or individual ad level. To do this globally: 1. Go to the Admin -> Account Settings page.\ ![](/files/K2Ew2pS4fHPVhYqUmrnE) 2. Under "Tracking" add `gacid={campaignid}` to the Final URL Suffix. If you are already using a Final URL Suffix, you will need to separate parameters with `&` .\ Note: If you set the Final URL Suffix in an ad, campaign, or ad group it will override this global setting, so you will need to append `&gacid={campaignid}` to the new Final URL Suffix. ### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Configure the [HIPAA allowlist](https://app.freshpaint.io/hipaa/allowlist) destination specific HIPAA allowlist 2. Edit the Event Properties allowlist and add the following properties: 1. `$gclid` or `$gbraid` or `$wbraid` 2. `ctname or ctid` ### That's it! Now all you need to do to send an event to Google Ads is enable the destination in the Freshpaint event definition: Navigate to your Freshpaint event, and toggle the destination on to enable the event to be sent to the Google Ads destination.
### Confirm and Validate Conversions in Google Ads
{% hint style="info" %} Data from the previous day may not be ingested and displayed by Google in your until 3:30pm ET the following day and can even take up to 24 hours to appear in your Google Ads conversion goals. {% endhint %} Congratulations! Once you have confirmed conversion in Google Ads, you have finished setting up this integration. You can find more detailed documentation on this integration in the [reference guide document.](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversions-api-reference) # Google Ads Conversions API Reference {% hint style="info" %} The Google Ads Conversion API requires setting up new Conversion Actions within Google Ads. If you want to re-use your existing Google Ads configuration, take a look at the [Google Ads Proxy Destination](/integrations/destinations/direct-response-ads/google-ads). {% endhint %} Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Refer to this destination as **Google Ads Conversion API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the Google Ads Conversions API destination. For information on how to set up this integration, see the[ Quick Start guide](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide). ### Events Freshpaint `.track()` events map to any **Click Conversions** you've already created in Google Ads. ## Track Events When you send an event to Google Ads, you can track conversions from your ad campaigns based on those events. ### Server-side You may provide the following additional event properties:
Freshpaint propertyGoogle Ads parameterTypeRequired?Description
$gclid or $gbraid or $wbraidgclid or wbraid or gbraidstringRequiredgclid (Google Click ID) is generated at ad click time and appended to the landing page URL. Freshpaint will automatically capture gclid for events from your website. If you wish, you may provide $gclid as an event property to override the automatically captured value. wbraid or gbraid can be used instead of gclid.
ctname or ctidctidstringRequiredThe Conversion Name or Conversion Id of the conversion action in Google Ads. When using the Conversion Name, the Freshpaint integration will lookup the conversion id before sending the event to google. When using the Conversion Id, the name of the Freshpaint Event must exactly match the name of the Google Ads Conversion name.
timeconversionDateTimenumberOptionalThe time the event occurred as a unix epoch. The time needs to be after the ad is clicked or it won't be accepted by google.
cart_datacartDataobjectOptionalThe cart data associated with this conversion. Google Docs
external_attribution_dataexternalAttributionDatalistOptionalAdditional data about externally attributed conversions. This field is required for conversions with an externally attributed conversion action, but should not be set otherwise. Google Docs
custom_variablescustomVariableslistOptionalThe custom variables associated with this conversion. Google Docs
conversion_environmentconversionEnvironmentenumOptionalThe environment this conversion was recorded on, for example, App or Web. Google Docs
value or total or revenuevaluenumberOptionalValue of the conversion. See About conversion values for more information
currencycurrency_codestringOptionalCurrency of the conversion value, "USD" by default. See the list of supported currency codes.
emailemailstringOptionalThe email address of the user
phone or phone_numberphonestringOptionalThe phone number of the user
mobile_idmobileIDstringOptionalMobile device ID (advertising ID/IDFA). Accepted only for Customer Match.
third_party_user_idthirdPartyUserIDstringOptionalAdvertiser-assigned user ID for Customer Match upload, or third-party-assigned user ID for Store Sales. Accepted only for Customer Match and Store Sales.
address_infoofflineAddressInfoobjectOptionalAddress information. Accepted only for Customer Match, Store Sales, and ConversionAdjustmentUploadService. Google Docs
order_idorderIDstringOptionalThe order ID associated with the conversion. An order id can only be used for one conversion per conversion action. Used to avoid duplicate conversions in Google Ads.
{% hint style="info" %} Freshpaint will only deliver events to Google when a user arrives on your site by clicking on a Google Ad, thus generating an `gclid`. Without `gclid`, Google will not be able to attribute conversions. {% endhint %} ## Setup Conversion Actions Please refer to the [Quick Start Guide](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversion-api-quick-start-guide#next-youll-need-to-setup-conversion-actions-in-google-a-ds-and-link-your-freshpaint-event-to-your-go) for instructions on how to set up conversion actions. ## Misc. Considerations * Conversions may take up to 24 hours to appear in your Google Ads Conversion Goals. * [Google Ads API v15 introduces a consent object](https://support.google.com/google-ads/answer/14546648?hl=en) to indicate whether users within the European Economic Area have consented to the event being shared with Google. If the event is enabled and consented to within Freshpaint using the Freshpaint consent management features, Freshpaint will automatically mark the event as consented to when sending the event to Google's servers. See [Consent Management](/integrations/consent-management) for more information. ## Conversion Event Imports Between Google Analytics and Google Ads The workflow of importing GA4 events as conversion actions in Google Ads is considered non-compliant, primarily related to the handling of user identifiers like the GCLID (Google Click Identifier). To remain compliant for both GA4 and Google Ads, Freshpaint recommends: * **Not allowlisting the Google Click Identifier (GCLID) property for your Google Analytics destination.** * **Creation of net-new Website Conversion Actions in Google Ads:** Instead of passing the GCLID directly to GA4, create specific Website conversion actions. The conversion action name can be used as the "ctname" property, along with a "conversion label" property which allows Freshpaint to map an event to a specific conversion action in Google Ads. * **Unlinking your Google Analytics 4 property from your Google Ads account:** The process for how these 2 tools are unlinked is documented [here](https://support.google.com/analytics/answer/9379420), under the "Unlinking Google Ads accounts from Analytics" section of the article. ## Authentication Freshpaint supports using either a User Account or Service Account for accessing the Google Ads Conversion API. #### User Account A user who has access to both Freshpaint and Google Campaign Manager 360 may delegate access to Freshpaint using the user account. Freshpaint will be granted the limited permissions necessary to send conversion events to google CM360 and be directly tied to the account of the user who delegated access. If that user account is removed or reset, google may revoke the authentication credentials that have been delegated to Freshpaint under that user account. {% hint style="info" %} The user delegating access to their User Account needs to have the "Insert offline conversions" permission as part of their role within Campaign Manager 360. {% endhint %} Navigate to the destination configuration page and click either `Connect` or `Reconnect` in the `Access Permission` row of the destination configuration page. In the popup dialog select User Account and then `Connect with Google CM360` which will redirect you to Google to complete setting up authentication between Freshpaint and Google services.
#### Service Account An account within google can be created only for Freshpaint that will provide Freshpaint with a set of credentials for Freshpaint to use when sending conversion events to Google. The creation of this account will require necessary permissions to the underlying google account. Please follow the Google documentation on the creation and configuration of a service account available at: {% hint style="info" %} The service account should be provided with the scope which will allow access to send conversion events to Google. {% endhint %} Once the service account has been created within Google, the credentials file can be uploaded to the Freshpaint application. Navigate to the destination configuration page and click either `Connect` or `Reconnect` in the `Access Permission` row. In the popup dialog select `Service Account` and upload the json file that google provided with the credentials for Freshpaint. ## View-Through Conversions and Retargeting Freshpaint does not currently support view-through conversions. We only support click-based conversions that include a `gclid`, `gbraid`, or `wbraid` parameter. Note that retargeting of anonymous users is not possible due to the absence of an identifier that can be used to retarget that user. # Google Ads Send advertising events directly to Google Ads from Freshpaint Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. {% content-ref url="/pages/uLi6ESIPAjeFvu92dT3D" %} [Google Ads Quick Start Guide](/integrations/destinations/direct-response-ads/google-ads/google-ads-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/QHSnXejWKUPq60VHQYIq" %} [Google Ads Reference](/integrations/destinations/direct-response-ads/google-ads/google-ads-reference) {% endcontent-ref %} # Google Ads Quick Start Guide Send advertising events directly to Google Ads from Freshpaint Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Google AdWords New** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Conversion IDs, you can choose a specific one by suffixing the Conversion ID, such as: **Google AdWords New::123456789.** You can retrieve this value from the Google Ads configuration page for the Conversion ID of interest. {% hint style="info" %} When no suffix is specified, all configured Conversion IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webtruetrue
Mobilefalsetrue
Serverfalsetrue
{% hint style="info" %} When using Server-Side connection mode you are using a Proxy Integration for Google Ads. This destination runs on Freshpaint's servers, but emulates a native installation of Google Universal Analytics Tag. That means the integration behaves the same as if you did a native installation of Google Universal Analytics Tag, but the data first flows through Freshpaint before it's sent to Google. [See our docs on proxy integrations for more information](/reference/faqs/what-is-a-proxy-integration). {% endhint %} {% hint style="info" %} If you’d like to send a server-side event to Google Ads (such as one generated from our [HTTP API](https://documentation.freshpaint.io/reference/developer/http-api), or an event from [CallRail](https://documentation.freshpaint.io/integrations/sources/callrail) or [Invoca](/integrations/sources/invoca)), we recommend using the **Google Ads Conversions API** destination for the best results. If you’d still prefer to use this Google Ads destination, please reach out to us at ****, and we’ll assist you in configuring your server event. {% endhint %} ## Getting Started ### What You'll Need 1. Your Google Ads Conversion ID 2. [Conversion Actions](https://support.google.com/google-ads/answer/12216226?hl=en) configured in your Google Ads account 3. Conversion Events configured in your Freshpaint account ### To set up Google Ads with Freshpaint, first follow these steps: 1. Get your Google Conversion ID. In your Google Ads account go to [Tools > Conversions](https://ads.google.com/aw/conversions). 2. Click on the relevant conversion action
3. Select Tag Setup
4. Select Use Google Tag Manager. This option will only be there for conversion actions created manually in Google Ads - click [here](https://support.google.com/google-ads/answer/12216226?hl=en#zippy=%2Cinstructions) for instructions on how to create this kind of conversion action in Google Ads.
5. Get the Conversion ID from the instructions
6. Go to the [Google Ads configuration page](https://app.freshpaint.io/destinations/apps/google-ads) in Freshpaint. 7. Configure your Tag ID. Paste the value that you copied from the previous step.
8. **Configure your connection mode.** If you are a HIPAA customer, configure connection mode to server-side. If not, you may choose either connection mode. Learn more about Connection Modes [here](https://documentation.freshpaint.io/faqs/what-is-the-difference-between-client-side-and-server-side-connection-mode). 9. If you are NOT a HIPAA customer and have chosen client-side connection mode, you'll need to setup Conversion Labels from Google Adwords for the actions you want to attribute, as shown below. If you are a HIPAA customer, you can skip this step. ![Conversion Labels in Google Analytics](/files/6twNSwN3DBlCWMpXY0jP) #### Add transformations that map your Freshpaint events to Conversion Labels: ![](/files/iOT9UukvyRJhu6Vkknvz) ### Next, you'll need to link your Freshpaint event to your Google Ads action Each conversion action in Google Ads uses a conversion label to uniquely identify the conversion action. Follow these steps to link your Freshpaint event to your Google Ads Action: 1. Go to [Tools > Conversions](https://ads.google.com/aw/conversions) and click on the conversion action you want to link 2. Select Tag Setup, then select the Use Google Tag Manager option
3. Copy the Conversion label under the instructions
4. Attach the conversion label to the related event in Freshpaint by creating a Transformation in Freshpaint: 1. Click on "Create New" in [Transformations](https://app.freshpaint.io/transformations) 2. Click "Modify Data" 3. Select your Freshpaint conversion event, select the Google Ads destination, then click Save & Add Transformations
4. Select the Send Constant Property transformation option, copy the Conversion label value, and send it as the conversion\_label property value
### If you are a HIPAA account, you will need to add event properties to the allowlist. If you are not a HIPAA account, you can skip this step. 1. Configure the [HIPAA allowlist](https://app.freshpaint.io/destinations/apps/google-ads/phiallowlist) 2. Edit the Event Properties allowlist and add the following properties: 1. conversion\_label 2. $gclid
{% hint style="info" %} Freshpaint will only deliver events to Google Ads when a user arrives on your site by clicking on your Google ad, and the Google Click ID value ([$gclid](https://support.google.com/google-ads/answer/9744275?hl=en)) is captured from the clickthrough url. Without a $gclid value, Google will not be able to attribute events to your ad campaigns. {% endhint %} ### That's it! Now all you need to do to send an event to Google Ads is enable the destination in the Freshpaint event definition: Navigate to your Freshpaint event, and toggle the destination on to enable the event to be sent to the Google Ads destination.
If you've configured multiple Google Ads Conversion IDs, you'll need to toggle each Conversion ID individually for each Freshpaint event. If you're using Google Tag Manager to send data to Google Ads, and you have multiple Conversion IDs enabled, you'll need to specify which Conversion ID(s) you'd like to enable the event for in the event tag. ### Confirm and Validate Conversions in Google Ads
{% hint style="info" %} Data from the previous day may not be ingested and displayed by Google in your until 3:30pm ET the following day and can even take up to 24 hours to appear in your Google Ads conversion goals. {% endhint %} Congratulations! Once you have confirmed conversion in Google Ads, you have finished setting up this integration. You can find more detailed documentation on this integration in the [reference guide document.](/integrations/destinations/direct-response-ads/google-ads/google-ads-reference) # Google Ads Reference Send advertising events directly to Google Ads from Freshpaint Optimize your Google Ads spend by attributing ad clicks to conversion and other key behaviors. ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **Google AdWords New** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * If you've configured multiple Conversion IDs, you can choose a specific one by suffixing the Conversion ID, such as: **Google AdWords New::123456789.** You can retrieve this value from the Google Ads configuration page for the Conversion ID of interest. {% hint style="info" %} When no suffix is specified, all configured Conversion IDs are selected for inclusion / exclusion. {% endhint %} * Connection Modes:
Client-sideServer-side
Webtruetrue
Mobilefalsetrue
Serverfalsetrue
{% hint style="info" %} When using Server-Side connection mode you are using a Proxy Integration for Google Ads. This destination runs on Freshpaint's servers, but emulates a native installation of Google Universal Analytics Tag. That means the integration behaves the same as if you did a native installation of Google Universal Analytics Tag, but the data first flows through Freshpaint before it's sent to Google. [See our docs on proxy integrations for more information](/reference/faqs/what-is-a-proxy-integration). {% endhint %} This is a reference document for the Google Ads destination. For information on how to set up this integration, see the[ Quick Start guide](/integrations/destinations/direct-response-ads/google-ads/google-ads-quick-start-guide). ## API Mapping ### Events Freshpaint.`track()` events map to any **Click Conversions** you've already created in Google Ads. Any `properties` you've created will be passed along as well. ## Track Events When you send an event to Google Ads, you can track conversions from your ad campaigns based on those events. ### Client-side Freshpaint uses the [Google Tag](https://support.google.com/google-ads/answer/11994839) to send events to Google Ads. You may provide the following additional event properties: | **Freshpaint property** | **Google Ads parameter** | **Type** | **Required?** | **Description** | | ----------------------- | ------------------------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------- | | `category` | `ec` | string | Optional | Event category defined as you wish. Can be used as an additional filter criterion for conversion goals. | | `revenue` | `gv` | number | Optional | Value of the conversion in USD. Must be between 0 and 9999999 with up to 3 decimal places. | ### Server-side {% hint style="warning" %} This is a Proxy Integration for Google Ads. This destination runs on Freshpaint's servers, but emulates a native installation of Google Universal Analytics Tag. That means the integration behaves the same as if you did a native installation of Google Universal Analytics Tag, but the data first flows through Freshpaint before it's sent to Google. [See our docs on proxy integrations for more information](/reference/faqs/what-is-a-proxy-integration). {% endhint %} {% hint style="info" %} The Proxy integration allows you to re-use your existing google ads configuration. If you're starting fresh, we recommend using the [Google Ads Conversion API](/integrations/destinations/direct-response-ads/google-ads-conversion-api) destination. {% endhint %} Freshpaint's servers use the same API as the client-side Google Tag. You may provide the following additional event properties: | **Freshpaint property** | **Google Ads parameter** | **Type** | **Required?** | **Description** | | ------------------------------- | ------------------------ | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$gclid` | `gclid` | string | Required | gclid (Google Click ID) is generated at ad click time and appended to the landing page URL. **Freshpaint will automatically capture gclid for events from your website**. If you wish, you may provide `$gclid` as an event property to override the automatically captured value. | | `conversion_label` | `label` | string | Required | The Conversion Label configured within google ads to identify which conversion action the event should trigger | | `$gbraid` | `gclgb` | string | Optional | gbraid is generated at ad click time and appended to the landing page URL. It will be used as the click ID if `$gclid` is not provided. | | `$wbraid` | `gclgb` | string | Optional | wbraid is generated at ad click time and appended to the landing page URL. It will be used as the click ID if `$gclid` and `$gbraid` are not provided. | | `transaction_id` | oid | string | Optional | Allows overriding the [Transaction ID](https://support.google.com/google-ads/answer/6386790) generated by Freshpaint with a custom id to avoid duplicate conversions in Google Ads. | | `_gcl_aw` or `gclaw` | `gclaw` | string | Optional | Defaults to the gclid | | | `gac` | string | Optional | The google analytics code. Will only be sent to google ads if configured within your account. | | | `gtm_ee` | string | Optional | Enable Enhanced Ecommerce on the event. | | `$title` | `tiba` | string | Optional | The title of the page being visited | | `$referrer` | `ref` | string | Optional | The referrer to the page being visited | | `user_agent_arch` | `uaa` | string | Optional | The User-Agent Architecture | | `user_agent_bitness` | `uab` | string | Optional | The User-Agent Bitness | | `user_agent_full_version_list` | `uafvl` | string | Optional | The User-Agent Full Version List | | `user_agent_mobileness` | `uamb` | string | Optional | The User-Agent Mobileness. Must be 1 for a mobile device and 0 for non-mobile devices. | | `user_agent_platform` | `uap` | string | Optional | The User-Agent Platform. | | `user_agent_platform_version` | `uapv` | string | Optional | The User-Agent Platform Version | | `user_agent_wow64` | `uaw` | string | Optional | The User-Agent WoW64 (Win32 on Win64) | | `utm_campaign` | `utm_campaign` | string | Optional | The advertising campaign the specific event belongs to | | `utm_source` | `utm_source` | string | Optional | The advertising source that the user followed to reach the site. | | `utm_medium` | `utm_medium` | string | Optional | The medium or channel that the user followed to reach the site. | | `utm_content` | `utm_content` | string | Optional | The content tag used to track the specific content or variation of an ad that the user followed to reach the site. | | `utm_term` | `utm_term` | string | Optional | The keywords the user used when searching that led to the ad impression. | | `$screen_height` | `u_ah` | number | Optional | The screen height of the device visiting the page | | `$screen_width` | `u_aw` | number | Optional | The screen width of the device visiting the page | | `$viewport_height` | `u_h` | number | Optional | The visible height of the web page | | `$viewport_width` | `u_w` | number | Optional | The visible width of the web page | | `u_tz` | `u_tz` | number | Optional | The timezone offset of the device | | `value` or `total` or `revenue` | `value` | number | Optional | Value of the conversion. See [About conversion values](https://support.google.com/google-ads/answer/3419241?hl=en#zippy=%2Cmeasure-transaction-specific-conversion-values%2Cconversion-value-currency) for more information | | `currency` | `currency_code` | string | Optional | Currency of the conversion value, "USD" by default. See the list of [supported currency codes](https://support.google.com/merchants/answer/160637?hl=en). | | `$os` | `os` | string | Optional | The operating system of the device. Freshpaint will only send this property if it is allowlisted. | {% hint style="info" %} Freshpaint will only deliver events to Google when a user arrives on your site by clicking on a Google Ad, thus generating an `gclid`, `gbraid`, or `wbraid`. Without one of these click IDs, Google will not be able to attribute conversions. {% endhint %} #### Setup Conversion Labels {% hint style="warning" %} If you are using conversion actions that trigger off of a Page load, you will need to create new manual conversion actions in google ads. Freshpaint does not pass the URL to google ads which could expose HIPAA sensitive data when using the server-side integration. {% endhint %} Each Google Adwords conversion action uses a conversion label to uniquely identify the conversion action. 1. Get your google conversion label. In you're google ads account go to [Tools > Conversions](https://ads.google.com/aw/conversions). 2. Click on the conversion action you're setting up
3. Select Tag Setup
4. Select Use Google Tag Manager
5. Get the Conversion label from the instructions
6. Configure a [transformation](/admin-panel/transformations) for the Event within Freshpaint to attach the conversion\_label or any other fields to send to the destination.
## Using Multiple Google Ads Accounts If you need to send conversion actions to more than one different Google Ads account, this can be achieved by configuring additional instances, each with its own Conversion ID. After doing this, you'll see them listed in the Overview list, for example:
You can then select which Conversion ID you want for a given Event using the toggles in your [Library](https://app.freshpaint.io/events/schema):
If you're using precision tracking, see [#destination-info](#destination-info "mention") above. If you're using the [Google Tag Manager integration](/integrations/google-tag-manager-integration) integration, you enter the specific Conversion ID on the Freshpaint GTM Template tag:
## Call Conversions To use Google Ads call conversions, you need to call `freshpaint.registerCallConversion`. If you have an existing Google Ads Call Conversion configuration that looks like: ```javascript gtag('config', , { 'phone_conversion_number': }); ``` You need to replace it with the following call to the Freshpaint SDK: ```javascript freshpaint.registerCallConversion('', ) ``` Here's an example: ```javascript freshpaint.registerCallConversion('AW-1234567/aLabel', '312-555-1212') ``` {% hint style="info" %} If you have call conversions configured through Google Tag Manager, you can use the Google Ads Call Conversions on the Freshpaint GTM Template instead of calling `freshpaint.registerCallConversion` directly. {% endhint %} ## Considerations {% hint style="info" %} Conversions may take up to 24 hours to appear in your Google Ads Conversion Goals. {% endhint %} ### Conversion Actions Configuration The way you set up your conversion actions can affect the data that shows in the Google Ads console downstream. For example, if you have your conversion action set up to "Count one conversion", only one click per user will be shown in your console. This means that even if recent events are triggered, if they are triggered by the same user and ad as a previous event that was already counted, it will not show again. You can read more about how click ids are generated by Google Ads [here](https://support.google.com/searchads/answer/7342044?hl=en). Similarly, the click through conversion setting on your conversion action can be important. For example, if you have a 30-day click through conversion setting on your conversion action, any of the corresponding events sent to Google Ads from outside that 30-day window will not be shown in the Google Ads console under that conversion action. You can read more about that [here](https://support.google.com/google-ads/answer/3123169?hl=en). ## Conversion Event Imports Between Google Analytics and Google Ads The workflow of importing GA4 events as conversion actions in Google Ads is considered non-compliant, primarily related to the handling of user identifiers like the GCLID (Google Click Identifier). To remain compliant for both GA4 and Google Ads, Freshpaint recommends: * **Not allowlisting the Google Click Identifier (GCLID) property for your Google Analytics destination.** * **Creation of net-new Website Conversion Actions in Google Ads**: Instead of passing the GCLID directly to GA4, create specific Website conversion actions. This method generates a "conversion label" which allows Freshpaint to map an event to a specific conversion action in Google Ads. * **Unlinking your Google Analytics 4 property from your Google Ads account.** The process for how these 2 tools are unlinked is documented [here](https://support.google.com/analytics/answer/9379420), under the "*Unlinking Google Ads accounts from Analytics*" section of the article. ## View-Through Conversions and Retargeting View-through conversions and retargeting are possible with the Google Ads Conversions API destination: {% content-ref url="/pages/eaBrwXFi2W4sXqt112cS" %} [Google Ads Conversions API Reference](/integrations/destinations/direct-response-ads/google-ads-conversion-api/google-ads-conversions-api-reference) {% endcontent-ref %} # LinkedIn Ads As of September 12, 2025, the LinkedIn Ads integration has been deprecated. To continue sending conversion data to LinkedIn, please migrate to our new [LinkedIn Ads Conversions API integration.](/integrations/destinations/direct-response-ads/linkedin-ads-conversions-api) Contact your Account Manager or email **** for assistance on the migration. # LinkedIn Ads Conversions API Send advertising events directly to LinkedIn Campaign Manager {% content-ref url="/pages/3IR7q9xCfRCDbxt0oeHE" %} [LinkedIn Ads Conversions API Quick Start Guide](/integrations/destinations/direct-response-ads/linkedin-ads-conversions-api/linkedin-ads-conversions-api-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/VBkU5yQU6gPGzgm92pb1" %} [LinkedIn Ads Conversions API Reference](/integrations/destinations/direct-response-ads/linkedin-ads-conversions-api/linkedin-ads-conversions-api-reference) {% endcontent-ref %} # LinkedIn Ads Conversions API Quick Start Guide ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **LinkedIn Ads Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
## Getting Started This guide enables you to fully enable the LinkedIn Ads Conversions API destination for your site. For simplicity the event used for demonstration purposes is the generic `Page View` event. For more complex events see[ our additional documentation](/readme/setting-up-your-events). Additionally this guide assumes you have the Freshpaint snippet installed on your site, if you do not please follow[ this guide](/readme/guides/quickstart/installing-freshpaint). 1. [Enable the Freshpaint LinkedIn Ads destination](#enable-the-linkedin-a-ds-destination) * If in HIPAA mode enable the required fields 2. [Find/create your conversion IDs](#your-first-conversion-id) 3. [Enable LinkedIn Ads destination for the appropriate events](#enable-linkedin-a-ds-events) 4. [Connect the conversion ID to appropriate events](#connect-conversion-id-to-events) 5. [Confirm and validate events](#confirm-and-validate-conversions-in-linkedin) ### Configure Freshpaint To configure your LinkedIn Ads Conversions API destination you will need to connect with LinkedIn via OAuth 2.0. Click the "Connect With LinkedIn" button on the destination configuration page to get started. You must have one of the following Ad Account Roles in LinkedIn to authenticate: * Account Billing Admin * Account Manager * Campaign Manager * Creative Manager
1. Customers that use HIPAA mode should then configure the required properties and enable `conversion_id`.
2. At least one of `$li_fat_id`, `email`, `acxiom_id`, or `oracle_moat_id` are required to send conversions to LinkedIn Ads Conversion API. Enable at least one of these properties under recommended properties.
3. Click "Enable" Once you've successfully authenticated and follow the steps above you can start sending events to LinkedIn Conversions API. ### Your First Conversion ID To configure your LinkedIn Ads Conversions API destination events, you'll first need at least one Conversion Rule. 1. Log in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) 2. Click `Measurement > Conversion tracking` on the left menu 3. Click `Create Conversion` 4. Click `Conversions API`
5. Select **'Direct API' as the Data Source**
6. Save the event ### Finding the Conversion ID Once you have created a Conversion Rule, you'll need to locate the Conversion ID to configure your Freshpaint events. 1. Log in to your LinkedIn campaign manager account 2. Select the ‘Measurement tab’ on the left toolbar 3. Select ‘Conversion tracking’ 4. Click into the applicable conversion event. 5. Reference the 2nd ID listed in the URL string – this is the numeric portion of the `conversion_id`, also known as the Conversion Rule ID (or `conversion_ruleid`) within LinkedIn Campaign Manager: `https://www.linkedin.com/campaignmanager/accounts/{account_id}/conversions/{conversion_ruleid}` 1. Your `conversion_id` will be `urn:lla:llaPartnerConversion:{conversion_ruleid}` 1. **Example**: With the URL `https://www.linkedin.com/campaignmanager/accounts/123/conversions/2233445566`, your final `conversion_id` will be `urn:lla:llaPartnerConversion:2233445566` {% hint style="danger" %} **Conversion rules must have a data source of 'Direct API', otherwise conversion events will not be able to be streamed to your account.** {% endhint %} ### Enable LinkedIn Ads Events 1. Navigate to the [Event Library](https://app.freshpaint.io/events/schema). 2. Select/create the event you want your `conversion_id` to be associated with. * In this example we are going to associate it with every page view for demonstration purposes. 3. At the bottom of the event page enable `LinkedIn Ads Conversions API`.
### Connect Conversion ID to Events The best way to send the required Conversion ID depends on how you're generating your events. Below are two of the most common scenarios. #### Using Autotrack 1. Navigate to [Event Transformations](https://app.freshpaint.io/transformations). 2. Click the `Create New` button. 3. Select `Modify Data.` * Select your event (in this demo we will select `Page View`) . * Select `LinkedIn Ads Conversions API` for the destination. 4. Set the following values for the transform fields. * `Send Constant Property` for transform type. * Your conversion ID for the property value. * `Text` for the property type. * `conversion_id` for property name.

Send conversion_id as a constant property transformation

#### Using the GTM Integration When using the [Google Tag Manager integration](/integrations/google-tag-manager-integration), the Conversion ID is specified by the Freshpaint LinkedIn Ads Conversions API tag:
### Confirm and Validate Conversions in Freshpaint 1. Navigate to your site and visit a page that should trigger your event (For demonstration purposes we will use [FreshHealth.co](https://www.freshhealth.co/)). 2. Add a query parameter called `li_fat_id` to the URL (Example: [https://www.freshhealth.co/?li\_fat\_id=TEST](https://www.freshhealth.co/)). 3. Trigger your event (Our demonstration event is any `Page View`). 4. Navigate to the [Event Verification tool](https://app.freshpaint.io/event-verification). 5. Select `LinkedIn Ads Conversions API` and verify your event went through. * This can take up to 90 seconds. 6. Verify the event is marked as `OK` or resolve missing property issues.

Our LinkedIn Ads event went through smoothly with all required properties in place

### Confirm and Validate Conversions in LinkedIn To check whether LinkedIn Ads is receiving events. 1. [Sign in to LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) 2. Click `Analyze > Conversion tracking` on the left menu. 3. Click on `Data sources` in the middle of the screen. The source status should show up as `Active` if receiving events from your website. More information on status definitions is available in the official [LinkedIn documentation](https://www.linkedin.com/help/lms/answer/a489395).

Example of conversion with no data

## Required Properties `$li_fat_id`, `email`, `acxiom_id`, and `oracle_moat_id` are all considered "external IDs" by LinkedIn. At least one of these properties is required to be allowlisted if in HIPAA mode. > External IDs provide a way to leverage unique/proprietary identifiers for improved signal quality and identity resolution. This helps in accurately matching users across devices and platforms, thereby enhancing the overall effectiveness of advertising efforts while complying with global privacy regulations. {% hint style="info" %} The following event properties are **required** in order to attribute events to specific ads, and if in HIPAA mode, must be selected in the Required Properties Allow List. {% endhint %}
Freshpaint propertyLinkedIn Ads
parameter		TypeRequirementDescription
conversion_idconversionstringRequiredA conversion rule ID provided by LinkedIn that allows you to trigger a specific event.

The conversion ID will have a similar format to: urn:li:sponsoredAccount:5123456
$li_fat_idLINKEDIN_FIRST_PARTY_ADS_TRACKING_UUIDstringRequired [conditional]A query parameter that connects a page view or conversion event to a specific ad, which Freshpaint captures as $li_fat_id.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
emailSHA256_EMAILstringRequired [conditional]The email address of the contact associated with the conversion event. Used for view-through conversions.

Use with caution. LinkedIn will be able to match hashes with original emails if the emails are recorded in their system.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
acxiom_idACXIOM_IDstringRequired [conditional]User identifier for matching with LiveRamp identity graph. Used for view-through conversions.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
oracle_moat_idORACLE_MOAT_IDstringRequired [conditional]User identifier for matching with Oracle MOAT Identity. Used for view-through conversions.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
# LinkedIn Ads Conversions API Reference ## Destination Info * Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls * Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode) * Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration) * Refer to this destination as **LinkedIn Ads Conversions API** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object) * Connection Modes:
Client-sideServer-side
Webfalsetrue
Mobilefalsetrue
Serverfalsetrue
This is a reference document for the LinkedIn Ads destination. For information on how to set up this integration, see the [LinkedIn Ads Conversions API Quick Start Guide](/integrations/destinations/direct-response-ads/linkedin-ads-conversions-api/linkedin-ads-conversions-api-quick-start-guide). ### Events When you send an event to the LinkedIn Ads Conversions API destination from Freshpaint, Freshpaint will create an event in the LinkedIn campaign manager by hitting LinkedIn's API. ## Track Events When you send an event to the LinkedIn Ads Conversions API destination, you can track conversions from your ads based on those events. Below are the Required, Recommended, and Optional properties which are mapped to the LinkedIn Ads Conversions API request:
Freshpaint propertyLinkedIn Ads
parameter		TypeRequirementDescription
conversion_idconversionIdstringRequiredA conversion ID provided by LinkedIn that allows you to trigger a specific event.

The conversion ID will have a similar format to: urn:li:sponsoredAccount:5123456
$li_fat_idLINKEDIN_FIRST_PARTY_ADS_TRACKING_UUIDstringRequired [conditional]A query parameter that connects a page view or conversion event to a specific ad, which Freshpaint captures as $li_fat_id.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
emailSHA256_EMAILstringRequired [conditional]Email hashed with SHA 256 algorithm. Used to improve match rates.

Use with caution. LinkedIn will be able to match hashes with original emails if the emails are recorded in their system.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
acxiom_idACXIOM_IDstringRequired [conditional]User identifier for matching with LiveRamp identity graph. Used for view-through conversions.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
oracle_moat_idORACLE_MOAT_IDstringRequired [conditional]User identifier for matching with Oracle MOAT Identity. Used for view-through conversions.

At least one of $li_fat_id, email, acxiom_id, or oracle_moat_id are required.
currency_codecurrencyCodestringOptionalCurrency code in ISO format (e.g. "USD")

Must be provided with amount
amountamountstringOptionalMonetary amount as a decimal string (e.g. "50.0")

Must be provided with currency_code.
first_namefirst_namestringOptionalUser's first name. Can improve match rates.

Unmasked PII. Use with caution.
last_namelast_namestringOptionalUser's last name. Can improve match rates.

Unmasked PII. Use with caution.
job_titletitlestringOptionalUser's job title. Can improve match rates.

Unmasked PII. Use with caution.
company_namecompany_namestringOptionalUser's company name. Can improve match rates.

Unmasked PII. Use with caution.
country_codecountry_codestringOptionalUser's country code. Can improve match rates.

Unmasked PII. Use with caution.
# LinkedIn Insights The LinkedIn Insights destination allows Freshpaint to pull campaign performance data (spend, clicks, conversions) from your LinkedIn ad account to power the Ad Performance and Insights Overview dashboard. This destination provides visibility into how your LinkedIn advertising spend drives appointments and revenue. {% hint style="info" %} This destination pulls data *from* LinkedIn—it does not send events to LinkedIn. If you need to send conversion events to LinkedIn, use the LinkedIn Ads Conversions API destination instead. {% endhint %} --- [Next Page](/llms-full.txt/1)