getInsights Documentation

Purpose

This node retrieve analytical data from a specified object within the Meta marketing ecosystem. It collects key performance indicators (KPIs) such as impressions, clicks, spend, and other metrics within a designated timeframe or date range. This function enables users to gain insights into the effectiveness of their marketing strategies and to make informed decisions based on this data.

Settings

The node accepts several settings, both through direct inputs and configuration through config. Each setting has a critical role in how the data is fetched and displayed. Below is the exhaustive detail of every setting:

1. objectId

• Input Type: String
• Description: This parameter requires the unique identifier corresponding to the object (like an ad account, campaign, ad set, or ad) from which insights will be retrieved. If this setting is not provided, the function will return an error message.
• Default Value: An empty string (if not provided).

2. fields

• Input Type: String
• Description: Lists the specific fields (KPI metrics) that you want to retrieve insights for. The default includes a selection of critical performance indicators: impressions, clicks, spend, ctr (click-through rate), cpc (cost per click), cpm (cost per thousand impressions), reach, frequency, and actions.
• Default Value: 'impressions,clicks,spend,ctr,cpc,cpm,reach,frequency,actions'

3. datePreset

• Input Type: String
• Description: Defines a preset date range for the insights to be retrieved. This can be adjusted according to user needs, offering various time frames such as 'last_7d', 'last_30d', etc. If left empty, it defaults to the last 30 days.
• Default Value: 'last_30d'

4. timeRange

• Input Type: String
• Description: Provides a more flexible option for specifying a custom date range beyond the included presets. The expected format should follow the API's requirements (usually a start and end date).
• Default Value: An empty string (if not provided).

5. level

• Input Type: String
• Description: Determines the granularity of data retrieval. This can be set to levels like campaign, adset, or ad. By default, this setting is not specified, which may yield data at the highest level available.
• Default Value: An empty string (if not provided).

6. limit

• Input Type: Numeric
• Description: Controls the maximum number of records returned by the function. This helps manage data size and performance. If not specified, defaults to a maximum of 50 records.
• Default Value: 50

How It Works

1. The function begins by gathering the required settings from the inputs and config objects. It defaults to pre-defined values if some inputs are missing.
2. The function checks whether the required objectId is provided; if not, it returns an error message indicating its necessity.
3. An integration instance is created to establish a connection with Meta’s APIs using a secure connection.
4. The function calls the getInsights method from the Meta integration to fetch the required data based on the provided criteria.
5. If successful, it formats the output to include the retrieved data and provides pagination information if applicable.
6. If any error occurs during this process, an error response is returned, indicating the nature of the issue.

Use Cases & Examples

Use Case 1: Campaign Performance Analysis

A digital marketing team wants to analyze the performance of their latest campaign over the last month to optimize future ad spend.

Use Case 2: A/B Testing Insights

An analyst runs multiple ad variations and needs to compare their performance based on clicks and impressions to determine which version is more effective.

Use Case 3: ROI Calculation

A financial officer wants to assess the return on investment (ROI) of their advertising efforts by comparing ad spend to revenue generated over a specific time frame.

Detailed Example:

Use Case: Campaign Performance Analysis

Configuration Sample:

{
    "inputs": {
        "objectId": "123456789",
        "fields": "impressions,clicks,spend,ctr",
        "datePreset": "last_30d",
        "timeRange": "",
        "level": "campaign",
        "limit": 100
    },
    "config": {}
}

Explanation: In this example configuration, the user retrieves insights specifically for a campaign identified by objectId "123456789". The metrics of interest are limited to impressions, clicks, spend, and click-through rate over the last 30 days. The granularity is set to the campaign level, allowing for focused analysis on campaign performance, and the limit is set at 100 to retrieve more data points. This configuration can help the marketing team adjust their strategy based on real-time performance data.