Table of Contents

Submitting a Facebook app for review

Facebook requires that third-party apps undergo a review process to ensure the safety of Facebook user's data. The following tutorial describes how to submit your Paid Media application for review and which permissions to request. For general information about the process, see App Review.

Facebook periodically changes the review process. Contact your Facebook account representative to help expedite the process.

This article is part of a series of tutorials on implementing Paid Media Manager for Pega Marketing. To read from the beginning, see Extending next-best-action to digital advertising platforms with Paid Media Manager.
  1. Log in to your App Dashboard.
  2. Select your Paid Media app.
  3. In the Products section of the left navigation panel, click Marketing API > Settings > App Review.
  4. In the Complete App Verification section of the Request for App Review window, click the Provide verification details icon.
  5. In the App Verification Details window, provide the following information:
    • Is a Facebook reviewer able to access or login to your app? - Select No
    • Why isn't a Facebook reviewer able to access or install your app? - Select My app doesn't use the Facebook Login dialog and Other.
    • Provide additional details on why a reviewer is not able to log in to your app, for example, This is not a customer-facing app. This is a server-to-server integration and this system can only be accessed by internal employees for the purposes of advertising to Pega customers.
       

      This Pega Marketing-based application generates Facebook Ads artefacts to target customers with offers selected by the Pega Marketing-based system. A customer may be selected to receive an offer for a new Credit Card A. We then create a custom audience and ad set for Credit Card A and associate them. Whenever a customer is selected for the Credit Card A offer they will be placed in that custom audience. If they are later selected for a Credit Card B offer the individual will be removed from the Credit Card A custom audience and placed in the Credit Card B custom audience. If an audience and ad set does not yet exist for that offer, it will be generated.

       

      We have around [number of] contacts who are targeted based on frequent interactions as well as nightly updates across our entire customer base. This can result in a high volume of API calls that results in rate-limits without standard access.

      Sample app verification details
      "Sample app verification details"
      Sample app verification details
  6. Click Save.
  7. Request the leads_retrieval permission for your app.
    1. In the Request for App Review window, click Add additional permissions and features.
    2. In the leads_retrieval section, click Request.
      Leads_retrieval permission
      "Leads_retrieval permission"
      Leads_retrieval permission
    3. Click Continue.
    4. In the Tell us how you'll use leads_retrieval section, click the Continue icon, and then enter a description of how your Paid Media app uses this permission, for example:

      The application exchanges data directly with Facebook APIs only. We use this permission to retrieve the leads that were generated from the Facebook.
       

      Sample API Call

      Get Leads by IDs

      This API is used to retrieve the Lead information for a Lead Gen ID.

      APINodeList<Lead> leads = Lead.fetchByIds(Lists.newArrayList(pageIdLeadGenIdMap.values()), REQUEST_FIELDS, context);
       

      The prerequisite for retrieving leads from Facebook is configuring the webhook. We provide the necessary endpoint and the verify token in the Paid Media Manager channels configuration for Facebook.

      1. A user fills the details through the Facebook lead ad displayed.

      2. Upon filling, a lead is generated and will be retrieved by our REST endpoint.

      3. We fetch the lead id and use it to fetch the details filled in the lead ad.

      4. We store the details as a prospect.
    5. Click Save.
  8. ​Request the manage_pages permission for your app.
    1. In the Request for App Review window, click Add additional permissions and features.
    2. In the manage_pages section, click Request.
    3. Click Continue.
    4. In the Tell Us Why Are You Requesting manage_pages section, click the Continue icon, and then enter a description of how your Paid Media app uses this permission, for example:
      The application exchanges data directly with Facebook APIs only. This permission is a dependent permission for the leads_retrieval permission. As per the Facebook permission guidelines, the permission is used in parallel to the leads_retrieval permission. We are not explicitly using this permission anywhere in our application. We require this permission to enable the leads and retrieve the lead ad data that is submitted by the user.
    5. Click Save.
  9. ​Request the ads_management permission for your app.
    1. In the Request for App Review window, click Add additional permissions and features.
    2. In the ads_management section, click Request.
    3. Click Continue.
    4. In the Tell Us Why Are You Requesting ads_management section, click the Continue icon, and then enter a description of how your Paid Media app uses this permission, for example:

      Sample API Calls

      Create Custom Audience

      This API is called to create a Custom Audience when a new offer is selected for the first time.

      APIRequest apiRequest = adAccount.createCustomAudience()

         .setName(audienceAction.getAudienceName())

         .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)

         .setDescription(audienceAction.getIdentifier())

         .setParam("customer_file_source", "USER_PROVIDED_ONLY");

      // If lookalike is enabled

      ((AdAccount.APIRequestCreateCustomAudience) apiRequest).setIsValueBased(true);

       

      Custom Audiences by Ad Set ID

      This API is used to find the Custom Audience related to an Ad Set based on the Ad Set Identifier. This API is called to identify the associated custom audience, when a customer clicks on the Ad whose ClickURL contains Ad Set ID as a parameter.

      List<AdSet> adSets = AdSet.fetchByIds(Collections.singletonList(adSetId), Collections.singletonList("targeting"), context);

      RawCustomAudience rawCustomAudience = adSets.get(0).getFieldTargeting().getFieldCustomAudiences().get(0);

       

      Delete Custom Audience

      This API is used to delete a custom audience. This is called on removal of an offer.

      CustomAudience customAudience = new CustomAudience(audienceId, context);

      customAudience.delete().execute();

       

      Get All Existing Audience

      This API is used to fetch all the existing audience during a campaign execution, to verify if an audience already exists for an offer.

      APIRequest apiRequest = adAccount.getCustomAudiences()

         .setParam("limit", "500")

         .requestFields(newArrayList("name", "description", "id", "approximate_count"));

       

      Create Lookalike Audience

      This API is used to create a Value Lookalike Audience, if the functionality is enabled in the application.

      APIRequest apiRequest = adAccount.createCustomAudience()

         .setName(audienceDTO.getAudienceName())

         .setSubtype(CustomAudience.EnumSubtype.VALUE_LOOKALIKE)

         .setDescription(audienceDTO.getIdentifier())

         .setOriginAudienceId(audienceDTO.getAudienceId())

         .setName(lookAlikeAudienceName)

         .setLookalikeSpec(audienceDTO.getLookAlikeSpec());

       

      Get All Ad Sets

      This API is used to retrieve the list of Ad Sets for a Campaign by Campaign ID. This is called to verify if an Ad Set already exists for an audience, if not a new Ad Set is created.

      APIRequest apiRequest = adAccount.getAdSets()

         .requestFields(Lists.newArrayList("id", "name", "campaign_id"))

         .setParam("limit", "500");

       

      Create Ad Set

      This API is used to create an Ad Set, and associate it to a Campaign and Custom Audience.

      AdAccount.APIRequestCreateAdSet adSetRequest = adAccount.createAdSet()

         .setName(audienceName)

         .setCampaignId(campaignId).setStatus(AdSet.EnumStatus.VALUE_PAUSED)

         .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)

         .setDailyBudget(100L)

         .setBidStrategy(AdSet.EnumBidStrategy.VALUE_LOWEST_COST_WITHOUT_CAP)

         .setTargeting(new Targeting().setFieldCustomAudiences(customAudiences));

       

      Get All Campaigns

      This API is used to retrieve the list of Campaigns for the Ad Account. This is called to verify if a Campaign already exists for an offer in the Ad account, if not a new Campaign is created.

      APIRequest apiRequest = adAccount.getCampaigns()

         .requestFields(Lists.newArrayList("id", "name"))

         .setParam("limit", "500");

       

      Create Campaign

      This API is used to create a Campaign for an offer.

      AdAccount.APIRequestCreateCampaign campaignCreateRequest = adAccount.createCampaign().setName(campaignName)

         .setObjective(Campaign.EnumObjective.VALUE_LINK_CLICKS)

         .setSpendCap(922337203685478L)

         .setStatus(Campaign.EnumStatus.VALUE_PAUSED);

    5. Upload a video walkthrough of the process, as required by Facebook.
    6. Click Save.
  10. ​Request the Standard Access permission for your app.
    1. In the Request for App Review window, click Add additional permissions and features.
    2. In the Standard Access section, click Request.
    3. Click Continue.
    4. In the Tell Us Why Are You Requesting Ads Management Standard Access section, click the Continue icon, and then enter a description of how your Paid Media app uses this permission, for example:

       

      We have a large number of contacts who are targeted based on frequent interactions as well as nightly updates across our entire customer base. This can result in a high volume of API calls that results in rate-limits without standard access. The campaigns configured run against millions of customers which requires better rate limiting. The Pega Marketing-based application generates Facebook Ads artefacts to target customers with offers selected by the Pega Marketing-based system. A customer may be selected to receive an offer for a new Credit Card A. We then create a custom audience and ad set for Credit Card A and associate them. Whenever a customer is selected for the Credit Card A offer they will be placed in that custom audience. If they are later selected for a Credit Card B offer the individual will be removed from the Credit Card A custom audience and placed in the Credit Card B custom audience. If an audience and ad set does not yet exist for that offer, it will be generated.

    5. Upload a video walkthrough of the process, as required by Facebook.
    6. Click Save.
  11. Submit the app for review.
Suggest Edit

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.