Support Home > Campaign Management > Create an Apple Search Ads Campaign

Create an Apple Search Ads Campaign

  • Feature Summary: The following document defines the process for creating an Apple Search Ads campaign within Kochava. Apple Search Ads is a mobile advertising platform which allows advertisements to be embedded into Apple products such as iPhones, iPods and iPads.

     

    iAd Framework vs AdServices Framework

    While both the iAd framework and AdServices framework produce attribution claims for Apple Search Ads claims, there are a number of notable differences.

     

    The AdServices Framework:

    • Supports attribution claims for devices on iOS14.3+ only.
    • Supports attribution claims for devices where the AppTrackingTransparency (ATT) setting is Opt-Out.
    • Has two types of payloads; a standard payload for cases where the ATT setting is Opt-Out and a detailed payload for cases where the ATT setting is Opt-In. The difference between the standard and detailed payload is that the standard payload does not contain a click timestamp.
    • Provides less campaign metadata than the iAd framework.
    • Will be the only source of Apple Search Ads attribution claims once the iAd framework is deprecated.
    • Requires that first an attribution token be generated on the client, which can then be used to retrieve attribution results.

    Overview of Attribution Claim Payload Differences:

    AdServices Detailed (Opt-In)AdServices Standard (Opt-Out)iAd
    attributionattributioniad-attribution
    orgIdorgIdiad-org-id
    campaignIdcampaignIdiad-campaign-id
    conversionTypeconversionTypeiad-conversion-type
    clickDateNot included on original payload. Optionally manufactured for the purpose of attribution.iad-click-date
    adGroupIdadGroupIdiad-adgroup-id
    countryOrRegioncountryOrRegioniad-country-or-region
    keywordIDkeywordIdiad-keyword-id
    creativeSetIdcreativeSetIdiad-creativeset-id
    iad-purchase-date
    iad-keyword
    iad-creativeset-name
    iad-lineitem-id
    iad-conversion-date
    iad-org-name
    iad-campaign-name
    iad-adgroup-name
    iad-keyword-matchtype
    iad-lineitem-name
    iad.iad-impression-date

     

    NOTES:

    • Apple Search Ads was formerly called iAd.
    • Apple Search Ads Campaigns are available for iOS apps only, no Postback is required and a tracking URL does not need to be provided to Apple Search Ads.

     

    Data Needed Before Beginning Process:

    • Kochava SDK must be implemented.
    • For retrieving claims via the AdServices framework, SDK version 4.4.0 or later must be implemented within the app. (Recommended)
    • NOTE: Apple Search Ads may also be utilized with a Server-to-Server integration. For more information refer to our Install Notification Setup support documentation.

     

    Use Cases for Apple Search Ads Campaign:

    • An app marketing campaign with Apple Search Ads has been created.

    Credentials — Apple Search Ads

    Account Limited Option: This feature is only available for Advanced and Enterprise package customers. Contact us for more information on upgrading your Kochava account.

     

    With the update to the AdServices framework for Apple Search Ads and shift from human-readable keywords and campaign metadata to numerical IDs, Kochava has released an update which retrieves and populated human-readable keywords and metadata. For descriptions of AdServices Attribution Payload, refer to their support documentation.

     

    1. Log in to Kochava.
    2. Select the desired Account and App.
    3. Select Apps & Assets > Partner Configuration.
    4.  

     

    1. In the available search box, type Apple Search Ads.
    2. Click on the Partner Configuration menu () > Credentials.
    3. Click Sign in with Apple.
    4. Enter the login credentials.
    5. NOTE: Sign in only needs to be completed in one app, also sign in with credentials that have access to all AdServices/ASA campaigns.

    6. Select the desired account.
    7. Select Account Read Only.
    8. Click Grant Access.
    9.  

      Apple Search Ads Permissions

       

    10. Click Save.

     

    ASA Keyword Location within Kochava:

    • Kochava query Match Object, attributed to Apple Search Ads.
    • Analytics when splitting or filtering by keyword.
    • Reporting, when the include SAN claim data specified.
    • NOTE: Kochava recommends adding the include SAN claim data in the traffic section of the report to receive all the available information Kochava gets from Apple.

     

    Possible Causes for Missing Keywords:

    • The user signed does not have the proper permissions for all campaigns associated to the app.
    • The keyword has been deleted from AdServices campaigns.
    • AdServices does not return a human readable keyword associated to the campaign ID/keyword ID combination.

    Create an Apple Search Ads Campaign

    BEST PRACTICES: It is HIGHLY recommended that a Tracker ID be appended to the partner campaign name e.g., the campaign name within the Apple Search Ads UI. The Tracker ID can be easily located within Kochava’s Campaign Manager, expand the section below for instructions on locating the ID.

    1. Once a tracker has been created, navigate to Campaign Manager.
    2. Locate and click on the desired Campaign.
    3. Located the desired Segment, and click on the expand arrow.
    4. Locate the desired Tracker, and click on the expand arrow.
    5. Locate and copy the Tracker ID.

     

    Locating Tracker ID

     

    1. Log in to Kochava.
    2. Select the desired Account and App.
    3. Select Links > Campaign Manager.
    4.  

     

    1. Click Add a Tracker or Select Segment Tools () > Add a Tracker.
      1. Select the Campaign.
      2. Select the Segment.

      NOTE: In order to streamline the Campaign/Segment/Tracker creation process a feature has been added to allow the creation of campaigns and segments while creating a new tracker. For more information about creating a campaign or segment while adding a new tracker, refer to our Create an Install Campaign support document. support documentation.

       

      Add a Tracker

       

    2. Enter a unique Tracker Name.
    3. Select the Tracker Type > Acquisition.
    4. NOTE: By default the Tracker Type is set to Acquisition.

    5. Select Media Partner > Apple Search Ads.
    6. Select an Agency Partner. (optional)
    7. Check Share with Publisher. (optional)
    8. Select Default Tracker:
      1. On
      2. Off (default)
      3. NOTE: Selecting On will allow SAN network traffic to funnel to the default tracker when no tracker ID is present. If a default tracker is not set up and the tracker ID is not appended to the partner campaign name, that data will be bucketed in the most recently set up tracker for that network.

    9. Enter the Install Destination URL.
    10. Enter a Deep Link. (optional)
    11. Select Apple Search Ads Organization IDs. (optional)
      • Select Organization IDs that you would like to be associated with this tracker. This allows you to split your Apple Search Ads traffic to multiple trackers based on Organization ID.
    12. NOTE: In order to select Organization IDs you must first enter them within Partner Configuration for Apple Search Ads. See Install Postback Configuration section for more details.

    13. Click Save. (If no further trackers need to be created)
    14. Click Save & Add Another Tracker. (If additional trackers need to be created).

     

    Acquisition Tracker Settings
    A. Campaign and Segment selection/creation section.


    Install Postback Configuration (Optional)

    This step is only needed if you wish to make changes to the default method of handling attribution for standard AdServices attribution payloads, which do not contain a click timestamp. Apple will provide a standard payload in cases where the user did not opt in via the AppTrackingTransparency framework. Within Partner Configuration for Apple Search Ads, you can determine whether or not to attribute these claims. If you choose to attribute, you can determine the click timestamp Kochava manufactures, relative to the user’s install timestamp. By default, this is set to attribute standard ATT opt-out payloads and manufacture a click timestamp that is 29 days prior to the user’s install timestamp.

    1. Select Apps & Assets > Partner Configuration.
    2.  

     

    1. Click Add a Configuration.
    2. Select Media Partner > Apple Search Ads.
    3. Click Go.
    4. Select Install > Postback Tools () > Edit.
    5. Leave the ATTRIBUTION FOR ATT OPT-OUT USERS box checked if you wish to attribute Apple Search Ads claims for ATT opt-out users. Uncheck if you do not wish to attribute attribution claims on these users. By default this will be checked.
    6. If the ATTRIBUTION FOR ATT OPT-OUT USERS is checked, you can determine how Kochava should manufacture a click timestamp, relative to the user’s install timestamp. As an example, if the MANUFACTURED CLICK TIMESTAMP is set to 29 days, Kochava will assign a click timestamp that is 29 days prior to the user’s install timestamp.
    7. Enter Organization IDs associated with this app.
    8. NOTE: Organization IDs can be found within your Apple Search Ads account and/or within your Apple Search Ads campaign management partner’s account. Once entered, they will be selectable when creating or editing a tracker. This allows you to segment your traffic to different trackers based on Organization ID. If you do not assign an Organization ID to a specific tracker, it will be awarded to your default Apple Search Ads tracker.

    9. Click Save.

    Track Redownloads with Apple

    ATTENTION: The Install Reprocessing Lookback window is applied to all re-installs for the app and will consider all channels, not just for the purposes of tracking redownloads with Apple Search Ads.

     

    Apply the Install Reprocessing Setting:

    1. Select Apps & Assets > Partner Configuration.
    2.  

     

    1. In the upper right hand corner of the screen, Select Tools > Default Reconciliation Settings.
    2. Select the desired Install Reprocessing Lookback window.
    3. Click Save.

    Create a Reengagement Tracker:

    1. Select Links > Campaign Manager.
    2.  

     

    1. Click Add a Tracker or Select Segment Tools () > Add a Tracker.
      1. Select the Campaign.
      2. Select the Segment.

      NOTE: In order to streamline the Campaign/Segment/Tracker creation process a feature has been added to allow the creation of campaigns and segments while creating a new tracker. For more information about creating a campaign or segment while adding a new tracker, refer to our Create an Install Campaign support document.

    2. Enter Tracker Name.
    3. Select Tracker Type > Reengagement.
    4. Select Media Partner > Apple Search Ads.
    5. Select an Agency Partner. (optional)
    6. NOTE: The Share With Publisher setting allows the associated publisher to view the settings for this tracker. If unchecked, the associated publisher will not be able to view the settings for this tracker.

    7. Select the Destination URL Type > Custom.
    8. Enter an Install URL.
    9. Enter a Deep Link. (optional)
    10. NOTE: Optional and only relevant when using deferred deeplinking.

    11. Enter a Custom Parameter. (optional)
    12. Select Event > _install for Redownload attribution.
    13. NOTE: The selected event(s) will be the point of conversion for the reengagement campaign. Attribution will be awarded to the click that led to the reengagement event based on attribution configuration. Any LTV (Lifetime Value) will also be awarded to the source that drove the reengagement.

      NOTE: The lookback window for each post-install event may be individually set. For more information on setting an event lookback window, refer to our Post-Install Event Creation and Configuration support documentation.

      NOTE: SessionBegin event is now available to be used for reengagement. One session a day is eligible to be reengaged per day.

    14. Click Save (If no further trackers need to be created).

     

    Reengagement Tracker


    Apple Campaign Association to a Specific Tracker in Kochava (Optional):

    Locating the Tracker ID within Kochava —

    Unless a specific tracker ID has been associated with the Apple Search Ads campaign, redownloads will be associated with the latest created reengagment tracker within Kochava.

    1. Locate the Tracker.
    2. Expand the tracker detail.
    3. Copy the Tracker ID.
    4.  

      Copy Tracker ID

     

    Adding the Kochava Tracker ID to a New Apple Search Ads Campaign —

    1. Enter Tracker ID along with campaign name during creation flow.
    2.  

      New ASA Campaign

     

    Adding the Kochava Tracker ID to an Existing Apple Search Ads Campaign —

    1. Log in to Apple Search Ads.
    2. Click on Campaign.
    3. Edit Campaign Settings.
    4. Add Kochava Tracker ID to the Campaign Name.
    5. Click Save.
    6.  

      Existing Campaign


    Apple’s Custom Product Pages

    Apple’s Custom Product Pages feature allows for the creations of additional versions of App Store product pages, each of which highlights a feature or specific content and allows the sharing of a page’s unique URL in corresponding marketing campaigns.

    Apple’s Custom Product Pages

     

    Example (Install Attributed to a Custom Product Page)

    "payload": {
    "adId": 7772137742,
    "creativeSetId": 0,
    "conversionType": "Download",
    "orgId": 7777680,
    "campaignId": 1037771923,
    "adGroupId": 1052146777,
    "countryOrRegion": "PH",
    "attribution": true
      }

    NOTE: In this example, the adId field matches the CPP ad id in the ASA dashboard under the Ads view. If the ad was not a custom product page then the adId does not seem to be present.

  • Feature Summary: The following document defines accessing data associated with Apple Search Ads campaign within Kochava. Apple Search Ads is a mobile advertising platform which allows advertisements to be embedded into Apple products such as iPhones, iPods and iPads. Apple Search Ads campaign data can be located with Analytics, Reporting and Query, details and suggestions for locating and organizing your data can be found below.

     

    Analytics

    Within Analytics filters may be used in order to organize and display Apple Search Ads data specifically.

    NOTE: In the following example, Analytics Events Volume will be used to illustrate the display of Apple Search Ads data. The same process for applying filters may be used within any of the other Analytics views.

    1. Log in to Kochava.
    2. Select the desired Account and App.
    3. Select Analytics > Events Volume.
    4.  

    1. Click Add a Filter.
    2. Select Network Name.
    3. Select Apple Search Ads.
    4.  

      Analytics Data
      A. Select Network Name > Apple Search Ads.
      B. It is highly recommended to split the data by Site.
      C. Mouseover to view specific data.


    Reporting

    1. Locate the desired report and Click Customize.
    2. Select Networks > Apple Search Ads.
    3. Adjust/Add/Remove any other settings.
    4. Click Create.
    5.  

      Reporting Data
      A. Including site and creative in the report can help organize your data.


      Query

      Below is a useful Query for understanding keyword and campaign-level performance for Apple Search Ads data. This Query must be run in Standard SQL dialect.

      SELECT
          DATE(i.date_occurred) AS install_date,
          CASE
              WHEN COALESCE(i.site_id, '') = '' THEN '--no keyword provided--'
              ELSE i.site_id END
          AS keyword,
          JSON_EXTRACT_SCALAR(i.match_object, '$.iad-campaign-name') AS campaign_name,
          JSON_EXTRACT_SCALAR(i.match_object, '$.iad-adgroup-name') AS adgroup_name,
          COUNT(DISTINCT i.install_id) AS install_count,
          COUNT(DISTINCT(CASE WHEN e.event_name = '_SessionBegin' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 0 AND 0 THEN e.event_id ELSE NULL END)) AS d0_session_count,
          COUNT(DISTINCT(CASE WHEN e.event_name = '_SessionBegin' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 1 AND 1 THEN e.event_id ELSE NULL END)) AS d1_session_count,
          COUNT(DISTINCT(CASE WHEN e.event_name = '_SessionBegin' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 2 AND 7 THEN e.event_id ELSE NULL END)) AS d2_d7_session_count,
          COUNT(DISTINCT(CASE WHEN e.event_name = '_SessionBegin' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 8 AND 30 THEN e.event_id ELSE NULL END)) AS d8_d30_session_count,
          COUNT(DISTINCT(CASE WHEN e.event_name = 'Purchase_New' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 0 AND 0 THEN e.event_id ELSE NULL END)) AS d0_purchase_count,  -- Adjust event names here
          COUNT(DISTINCT(CASE WHEN e.event_name = 'Purchase_New' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 1 AND 1 THEN e.event_id ELSE NULL END)) AS d1_purchase_count,  -- Adjust event names here
          COUNT(DISTINCT(CASE WHEN e.event_name = 'Purchase_New' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 2 AND 7 THEN e.event_id ELSE NULL END)) AS d2_d7_purchase_count,  -- Adjust event names here
          COUNT(DISTINCT(CASE WHEN e.event_name = 'Purchase_New' AND TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 8 AND 30 THEN e.event_id ELSE NULL END)) AS d8_d30_purchase_count,  -- Adjust event names here
          COUNT(DISTINCT(CASE WHEN TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 0 AND 0 THEN e.install_id ELSE NULL END)) AS d0_retention,
          COUNT(DISTINCT(CASE WHEN TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 1 AND 1 THEN e.install_id ELSE NULL END)) AS d1_retention,
          COUNT(DISTINCT(CASE WHEN TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 2 AND 7 THEN e.install_id ELSE NULL END)) AS d2_d7_retention,
          COUNT(DISTINCT(CASE WHEN TIMESTAMP_DIFF(e.date_occurred, i.date_occurred, DAY) BETWEEN 8 AND 30 THEN e.install_id ELSE NULL END)) AS d8_d30_retention
      FROM
          (
                (
                  SELECT
                      '_Install' AS event_name,
                      date_occurred,
                      install_id,
                      kochava_device_id,
                      site_id,
                      match_object
                  FROM installs_primary
                  WHERE network_name = 'Apple Search Ads'
                      AND install_id <> '0'
                      AND DATE(date_occurred) >= DATE_ADD(CURRENT_DATE(), INTERVAL -60 DAY) -- Adjust install cohort start date here
                      AND DATE(date_occurred) <= DATE_ADD(CURRENT_DATE(), INTERVAL -30 DAY) -- Adjust install cohort end date here
                ) i
            LEFT OUTER JOIN
                (
                  SELECT
                      event_name,
                      date_occurred,
                      install_id,
                      event_id,
                      kochava_device_id
                  FROM events_primary
                  WHERE network_name = 'Apple Search Ads'
                      AND install_id <> '0'
                      AND DATE(date_occurred) >= DATE_ADD(CURRENT_DATE(), INTERVAL -60 DAY) -- Adjust to match install cohort start date here
                      AND event_name IN ('_SessionBegin', 'Purchase_New') -- Adjust event names here
                ) e
            ON i.install_id = e.install_id AND e.date_occurred BETWEEN i.date_occurred AND TIMESTAMP_ADD(i.date_occurred, INTERVAL 30 DAY)
          )
      GROUP BY install_date, keyword, campaign_name, adgroup_name
      ORDER BY install_date, install_count DESC 

 
 

Last Modified: Oct 11, 2023 at 9:04 am