Branding for app metrics

App metric branding is available to all apps using OAuth.

What are app metrics?

Metrics are essentially an event category, while events are individual, time-stamped instances of a metric. App metrics are metrics that Klaviyo can identify as being created by your app - that is, metrics created via OAuth.

App metrics become branded when they have an application icon (branding) associated with them. They can be filtered in the Metrics tab by integration name:

📘

Unbranded app metrics are metrics that are identified as coming from your app but lack an associated icon. These will appear with a cog icon until an icon is uploaded.

App metrics are different from API metrics. API metrics are not able to be identified as coming from your app and have a cog icon associated with them. API metrics can be filtered by selecting API in the Metrics tab:

Set up branding

In order for your app’s metrics to be branded, you must:

1. Make sure you’re sending server-side events via OAuth and proxying any client-side events through your server and sending them via OAuth. Server-side OAuth events can be branded because we can authenticate who you are.
   • Events sent via private key and events sent via client-side APIs that make use of the Public API Key / Site ID (e.g., /client/events/) cannot be branded. Client-side events cannot be branded because there is no authentication mechanism to confirm the event is coming from your app. These are considered API metrics and will appear with a cog icon in Klaviyo.
   • If you send events via branded app metric and API metric methods, you’ll want to keep them separate to avoid divergent metrics (see Important considerations below for more information). Specifically, you should not be sending the same event via a branded app metric and API metric method.
2. Submit the integration registration form found in our OAuth guide. We will reach out via email and import your assets on your behalf. Before your icon is uploaded, any events meeting the branded event criteria will show up with the cog icon:
   

Here’s a diagram showing which events will be branded:

Migrating historical metrics

Going forward, metrics that meet the criteria in the diagram above will be branded automatically.

If your pre-existing app has historical API metrics, we will automatically migrate them to branded app metrics (on a per-metric basis) when a Klaviyo user installs your OAuth app via the following process:

• When an event meeting the branding criteria enters our system, we will check to see if there’s an API metric with the same name.
• We will check over 24 hours to see if that event is only sent via OAuth. If the same event is sent via API key and OAuth during this period, we will not brand the metric.
• We will also check to make sure that there are not multiple apps sending the same metric name for the same customer. If this is the case, we won’t be able to brand the metric (though this is not expected to happen frequently).

If the above conditions are met, we will brand the event.

Important considerations

It is important to avoid divergent metrics. Divergent metrics are two or more distinct metrics with unique metric IDs that share the same name, but come from different sources.

Divergent metrics most commonly occur when an event with the same name is sent via a “branded app metric” method and an “API metric” method. This results in two separate metrics in Klaviyo (with two different icons) which then cannot be utilized together in Klaviyo. You should avoid divergent metrics because they can break flows, segments, and reports associated with the metric.

For example, say that you start sending a new metric (named Added to Cart) via both /api/events with OAuth, and /client/events with a public key. This would result in a divergent metric and you would see two different metric types in your account. Those sent via OAuth would appear with your icon, and those send via public key would appear with a cog:

Any flows, segments, reports, etc., that you build with one of these metrics (branded or API) would only reflect some of your Added to Cart data, since the metric has diverged.

To avoid divergent metrics:

• Avoid sending the same metric name via a branded and API method. If you’d like to send both branded and API events, you should keep them separate and know that API metrics will appear with a cog icon. Our automatic process for migrating historical metrics should help you avoid divergent metrics.
• Avoid changing the name of a metric. For instance, you have an app called “Apptastic”. You name a metric Apptastic Shipment Delivered, but later change the name to Shipment Delivered. These metrics would diverge.

🚧

While our system will handle the move from an API metric to a branded app metric, you cannot move from a branded app metric to an API metric - this will result in a divergent metric.

Additional resources

• Set up OAuth
• Drive integration adoption