Apple Search Ads Integration for Nodus
1. Introduction to the Apple Search Ads Integration
What Is This Integration?
The Apple Search Ads integration connects your Apple Search Ads platform data with Nodus, allowing you to extract, analyze, and transform campaign performance metrics, ad insights, and keyword analytics. This integration functions as a source connector, bringing your Apple Search Ads data into the Nodus ecosystem for advanced analytics and business intelligence.
Prerequisites:
- An Apple Search Ads Advanced account with Account Admin or API Account Manager role
- Apple Search Ads credentials: Client ID, Team ID, Key ID, and Organization ID
- Permission to upload a public key to your Apple Search Ads account
Connection Overview:
The integration uses Apple Search Ads Reporting API to extract advertising performance data and metrics. Authentication is handled through Apple's client credentials with a public/private key pair system, and the connector extracts data based on predefined report templates.
2. Platform Setup Documentation (Setup Form for Apple Search Ads)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and Apple Search Ads by providing the necessary authentication credentials and account identifiers.
Field-by-Field Breakdown:
Integration Name
- Field Name & Label: Integration Name
- Description & Purpose: A descriptive name to identify this Apple Search Ads integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "Apple Search Ads - iOS App", "ASA - Main Account"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Apple Search Ads account or app.
Nodus Apple Search Ads Public Key
- Field Name & Label: Nodus Apple Search Ads Public Key
- Description & Purpose: The public key you'll need to upload to your Apple Search Ads account for authentication.
- Validation Rules & Format: Pre-filled text field with copy option.
- Troubleshooting Tips: This key is automatically generated. You'll need to copy this key and upload it to your Apple Search Ads account in the Account Settings > API section.
Apple Search Ads Client ID
- Field Name & Label: Apple Search Ads Client ID
- Description & Purpose: The client identifier used for authenticating with Apple Search Ads API.
- Validation Rules & Format: Alphanumeric string, required field.
- Examples: "SEARCHADS.27a4f510-f5ef-9820-87f1-219s74ztr99c"
- Troubleshooting Tips: You can find this value in Apple Search Ads dashboard under Account Settings > API after uploading the public key.
Apple Search Ads Team ID
- Field Name & Label: Apple Search Ads Team ID
- Description & Purpose: The team identifier for your Apple Developer account.
- Validation Rules & Format: Alphanumeric string, required field.
- Examples: "ABCD1234EF"
- Troubleshooting Tips: Available in Account Settings > API after uploading the public key.
Apple Search Ads Key ID
- Field Name & Label: Apple Search Ads Key ID
- Description & Purpose: The identifier associated with the key pair used for authentication.
- Validation Rules & Format: Alphanumeric string, required field.
- Examples: "a1b2c3d4e5"
- Troubleshooting Tips: Available in Account Settings > API after uploading the public key.
Apple Search Ads Organization ID
- Field Name & Label: Apple Search Ads Organization ID
- Description & Purpose: The unique identifier for your organization in Apple Search Ads.
- Validation Rules & Format: Numeric string, required field.
- Examples: "123456789"
- Troubleshooting Tips: Found in the URL when viewing your organization in the Apple Search Ads dashboard or in the Account Settings.
External Link
- Link Label: "Apple Search Ads Documentation"
- URL: https://searchads.apple.com/help/campaigns/
- Purpose: Provides access to official Apple Search Ads documentation for additional help.
Step-by-Step Guide:
- Log in to Apple Search Ads Advanced with an account administrator role
- Go to Users menu in the top-right corner and select your account
- Select Account Settings > User Management
- Click Invite Users and invite a user with API Account Manager role
- Copy the Public Key from the Nodus setup form
- In the Search Ads dashboard, go to Account Settings > API for the invited user
- Paste the public key in the Public Key field and click Save
- Copy the clientId, teamId, and keyId values displayed in the code block
- Enter these values along with your Organization ID and a meaningful Integration Name in the Nodus setup form
- Validate and save the connection
Reference Links:
3. Extraction/Query Configuration (Extraction Form for Apple Search Ads)
Purpose & Overview
This section explains how to configure data extraction from Apple Search Ads. The platform offers various templates for extracting different types of performance reports.
Template & Field Documentation:
Template Selection
- Field Name & Label: Select a template
- Description & Purpose: Defines which type of Apple Search Ads data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- AdGroup Report Template - Performance metrics for ad groups including impressions, taps, and installs
- Campaign Report Template - Campaign-level performance metrics and spend
- Ad Report Template - Creative-level performance data including tap through rates
- Keyword Report Template - Keyword performance and bidding metrics
Lookback Range
- Field Name & Label: Lookback Range
- Description & Purpose: Specifies how many days back to extract data
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- 3-day Range
- 7-day Range
- 28-day Range (recommended)
- 90-day Range
- Troubleshooting Tips: Apple Search Ads API may have limitations on historical data retrieval for certain metrics.
Historic Date Selection
- Field Name & Label: Historic Date
- Description & Purpose: For historical data extraction, specifies a custom date range
- Validation Rules & Format: Date picker, required field
- Troubleshooting Tips: Apple Search Ads typically maintains historical data but older data may have limitations.
Workflow & Examples:
- Select the appropriate template (e.g., "Campaign Report Template" for campaign-level data)
- Choose a lookback period or specific historic date range
- Preview the query to confirm configuration
- Execute extraction
Example Use Cases:
Campaign Performance Analysis:
- Template: Campaign Report Template
- Metrics: Impressions, taps, installs, spend
- Lookback: 28-day Range
Keyword Optimization:
- Template: Keyword Report Template
- Metrics: Keyword performance, bid amounts, conversions
- Lookback: 90-day Range
Ad Creative Analysis:
- Template: Ad Report Template
- Metrics: Creative performance, tap-through rates, conversion rates
- Lookback: 28-day Range
4. Data Mapping & Underlying Models for Apple Search Ads
Data Model Overview
The Apple Search Ads API returns structured report data based on the selected template. Each template corresponds to specific report types and data structures within the Apple Search Ads Reporting API.
Schema & Field Mapping
Ad Report Schema
| Field | Description |
|---|---|
| ad_id | The unique identifier of the ad |
| ad_name | The name of the ad |
| ad_group_id | The parent ad group identifier |
| campaign_id | The parent campaign identifier |
| creative_id | The creative identifier |
| creative_type | The type of creative |
| status | The status of the ad |
| impressions | Number of ad impressions |
| taps | Number of ad taps (clicks) |
| ttr | Tap-through rate (taps/impressions) |
| avg_cpt | Average cost per tap (JSON object with currency and amount) |
| local_spend | Amount spent in local currency (JSON object with currency and amount) |
| total_installs | Total number of app installs |
| total_new_downloads | Number of new app downloads |
| total_redownloads | Number of app redownloads |
| view_installs | Number of installs from ad views (without taps) |
| tap_installs | Number of installs following ad taps |
| tap_new_downloads | Number of new downloads following taps |
| tap_redownloads | Number of redownloads following taps |
| view_new_downloads | Number of new downloads from views |
| view_redownloads | Number of redownloads from views |
| total_install_rate | Overall installation rate |
| tap_install_cpi | Cost per install for tap installs (JSON object with currency and amount) |
| tap_install_rate | Installation rate from taps |
| date | The date for the metrics |
Ad Group Report Schema
| Field | Description |
|---|---|
| ad_group_id | The unique identifier of the ad group |
| ad_group_name | The name of the ad group |
| ad_group_status | The status of the ad group |
| campaign_id | The parent campaign identifier |
| device_class | Device type (iPhone, iPad, etc.) |
| impressions | Number of ad impressions |
| taps | Number of ad taps |
| ttr | Tap-through rate (taps/impressions) |
| avg_cpt | Average cost per tap (JSON object with currency and amount) |
| avg_cpm | Average cost per thousand impressions (JSON object with currency and amount) |
| local_spend | Amount spent in local currency (JSON object with currency and amount) |
| total_installs | Total number of app installs |
| total_new_downloads | Number of new app downloads |
| total_redownloads | Number of app redownloads |
| total_avg_cpi | Average cost per install (JSON object with currency and amount) |
| ad_group_serving_status | Current serving status of the ad group |
| ad_group_display_status | Display status of the ad group |
| pricing_model | Pricing model used (CPT, etc.) |
| default_bid | Default bid amount (JSON object with currency and amount) |
| start_time | Start time of the ad group |
| end_time | End time of the ad group (null if ongoing) |
| date | The date for the metrics |
Campaign Report Schema
| Field | Description |
|---|---|
| campaign_id | The unique identifier of the campaign |
| campaign_name | The name of the campaign |
| campaign_status | The status of the campaign |
| country_or_region | The country or region targeted |
| org_id | The organization identifier |
| impressions | Number of ad impressions |
| taps | Number of ad taps (clicks) |
| ttr | Tap-through rate (taps/impressions) |
| avg_cpt | Average cost per tap (JSON object with currency and amount) |
| avg_cpm | Average cost per thousand impressions (JSON object with currency and amount) |
| local_spend | Amount spent in local currency (JSON object with currency and amount) |
| total_installs | Total number of app installs |
| total_new_downloads | Number of new app downloads |
| total_redownloads | Number of app redownloads |
| total_avg_cpi | Average cost per install (JSON object with currency and amount) |
| date | The date for the metrics |
Keyword Report Schema
| Field | Description |
|---|---|
| keyword_id | The unique identifier of the keyword |
| keyword | The keyword text |
| keyword_status | The status of the keyword |
| match_type | Match type (exact, broad, etc.) |
| bid_amount | The bid amount for the keyword (JSON object with currency and amount) |
| ad_group_id | The parent ad group identifier |
| ad_group_name | The name of the parent ad group |
| impressions | Number of ad impressions |
| taps | Number of ad taps |
| ttr | Tap-through rate (taps/impressions) |
| avg_cpt | Average cost per tap (JSON object with currency and amount) |
| local_spend | Amount spent in local currency (JSON object with currency and amount) |
| total_installs | Total number of app installs |
| total_new_downloads | Number of new app downloads |
| total_redownloads | Number of app redownloads |
| view_installs | Number of installs from ad views (without taps) |
| tap_installs | Number of installs following ad taps |
| tap_new_downloads | Number of new downloads following taps |
| tap_redownloads | Number of redownloads following taps |
| view_new_downloads | Number of new downloads from views |
| view_redownloads | Number of redownloads from views |
| total_avg_cpi | Average cost per install (JSON object with currency and amount) |
| total_install_rate | Overall installation rate |
| tap_install_cpi | Cost per install for tap installs (JSON object with currency and amount) |
| tap_install_rate | Installation rate from taps |
| date | The date for the metrics |
5. Troubleshooting & FAQs for Apple Search Ads
Common Issues & Error Messages
Authentication Failures
- Error: "Invalid authentication credentials" or "Unauthorized access"
- Solution: Verify your Client ID, Team ID, Key ID, and Organization ID. Ensure the public key is properly uploaded to Apple Search Ads.
Permission Issues
- Error: "Insufficient permissions" or "Access denied"
- Solution: Ensure the user you've invited has the API Account Manager role. The API Read Only role doesn't always provide sufficient permissions.
Missing Data
- Common Causes:
- Date range outside of data retention period
- Insufficient account activity to generate data
- Solution: Adjust template filters, check date ranges
Organization Access
- Error: "Organization not found" or "Invalid organization ID"
- Solution: Verify that the Organization ID is correct and that your API user has access to that organization.
Logging & Diagnostic Tools
- Apple Search Ads dashboard provides UI reports that can be used to verify data
- Enable verbose logging in Nodus to capture API request/response details
- Use the Apple Search Ads Reporting API documentation for reference
Contact & Support Information
- Apple Search Ads Support: https://searchads.apple.com/help
- Nodus Support: support@nodus.com
API Key Management
Apple Search Ads uses a client credentials with certificate authentication:
- Public keys must be uploaded to Apple Search Ads Account Settings
- Credentials include Client ID, Team ID, and Key ID
- Organization ID is required to specify which organization to access
- Credentials don't expire but can be revoked at any time
Data Retention & Limitations
- Apple Search Ads typically retains report data for up to 24 months
- Some reports may have shorter retention periods
- The API has limits on the number of concurrent requests
- Daily reporting is the most granular time period available for most report types