Meta Integration Documentation for Vantage

Overview

The Meta Integration for the Vantage analytics and data platform allows users to connect to various Meta (formerly Facebook) APIs such as the Graph API, Threads API, and WhatsApp Cloud API. This integration enables functionalities like fetching ad accounts, campaigns, ad sets, ads, and marketing insights. By utilizing this integration, users can leverage data from their Meta advertising activities for better analytics, reporting, and decision-making.

Purpose

The primary purpose of the Meta Integration is to facilitate seamless interaction with Meta's marketing APIs, enabling users to access and manipulate advertising data effectively. This integration serves marketers, data analysts, and businesses looking to analyze and optimize their advertising strategies on Meta platforms.

Settings

The Meta Integration requires specific settings to operate correctly. Each setting's purpose, type, and implications on the integration are detailed below:

1. Encrypted Record

• Input Type: String
• Description: This record contains sensitive credentials, such as access tokens, which must be securely encrypted. It is essential for authenticating and authorizing requests to Meta APIs. Modifying this input without proper encryption can lead to access issues.
• Default Value: N/A (must be provided)

2. Service ID

• Input Type: String
• Description: This ID references the specific service that the integration will interact with, categorizing the data and requests appropriately. Changing this value affects the service context for API calls.
• Default Value: N/A (must be provided)

3. Client ID

• Input Type: String
• Description: This ID is associated with the specific client account using the Meta APIs. It is vital for tracking and managing requests for the right client. Altering this may redirect the integration to a different client account.
• Default Value: N/A (must be provided)

4. Credential ID

• Input Type: String
• Description: This ID is tied to the storage of access tokens and credentials in the database. It helps in managing user sessions and access. If changed, the integration may lose connection to previously stored credentials, requiring re-authentication.
• Default Value: N/A (must be provided)

5. Access Token

• Input Type: String
• Description: The access token grants authorization to make API requests on behalf of the user. It is crucial for interacting with most Meta APIs. Tokens expire, and proper management (refreshing/updating) is necessary for continuous operation.
• Default Value: N/A (must be obtained via authentication)

6. Token Expiry

• Input Type: Date
• Description: This timestamp indicates when the current access token will expire. Monitoring and managing the expiry is necessary to maintain continuous access to the Meta APIs. If the value changes, it necessitates refreshing the token.
• Default Value: N/A (set after authentication)

How It Works

The Meta Integration operates by first establishing a connection using the provided credentials, allowing for the retrieval, management, and interaction with the Meta APIs. Key procedural elements include:

1. Token Management:

   • The integration retrieves an access token, refreshing it when necessary to maintain authorized access.
   • Token refresh flows are specific to the type of Meta service being accessed (e.g., Instagram, Threads, Facebook).

2. Making Requests:

   • The integration dynamically adjusts request settings based on the target service's requirements (e.g., whether to include the access token as a header or query parameter).

3. Handling Responses:

   • The integration processes the responses from Meta APIs, managing errors gracefully and retrying requests in case of expired tokens.

Data Expectations

The Meta Integration expects specific data formats and structures when interacting with Meta APIs:

• Request Payloads: Depending on the specific API endpoint being called, detailed parameters (such as fields and filters) are expected in the request payload to tailor the responses.
• Response Data: Expected responses are typically in JSON format and may require parsing to extract specific metrics or insights.

AI Integrations

Currently, there are no specific AI integrations outlined in the Meta Integration code. However, the structured data obtained from Meta’s APIs can be utilized for downstream AI analytics, predictive modeling, or machine learning applications within the Vantage platform.

Billing Impact

The integration itself does not have direct billing implications; however, the activities conducted via the Meta APIs (such as ad spending) can impact billing associated with advertising costs on Meta. Users should monitor their ad accounts separately through the integration to avoid unexpected charges.

Use Cases & Examples

Use Case 1: Enhanced Advertising Insights

A digital marketing agency wants to improve their client’s advertising performance by analyzing past ad campaigns. They can use the Meta Integration to pull data on ad performance and adjust strategies accordingly.

Use Case 2: Cross-Platform Campaign Management

A business operates across multiple social media platforms and wants to manage its advertising campaigns centrally. The Meta Integration allows them to fetch and manage campaigns from Meta.

Detailed Example Configuration

Scenario: A business wants to retrieve advertising insights for a specific campaign over the last 30 days.

Sample Configuration Data:

const metaIntegrationConfig = {
    encryptedRecord: 'encrypted_credentials',
    serviceId: '12345',
    clientId: 'client_abc',
    credentialId: 'cred_abc123',
    tokenExpiry: '2024-12-31T00:00:00Z',
};

// Example function to get campaigns
async function retrieveCampaignInsights(adAccountId) {
    const options = {
        fields: 'id,name,status,objective,daily_budget',
        limit: 50,
        effectiveStatus: 'ACTIVE',
    };

    const campaigns = await metaIntegrationConfig.getCampaigns(adAccountId, options);
    console.log(campaigns);
}

By configuring the integration, users can efficiently retrieve advertising data and utilize it for informed decision-making and strategic planning.