Streamlined Free Listings plus Paid Ads for the onboarding flow

[eason9487]

Objective

• An onboarding flow for the integration offers merchants a choice of selecting Free Listings plus Paid Ads.
• The ability for merchants to:
  • preview the ads or campaigns they are about to launch,
  • know how many products will be synced to Google Merchant Center,
  • and set up billing for their Google Ads account via a popup.

💡 We will create a shared branch feature/1610-streamlined-onboarding. All relevant developments should be branched from it and merged back into it. And open a PR to merge the shared branch to develop once the overall features get ready to release.

Terminology

• FL: Free Listings

Technical - Frontend

The UI changes are mainly applied to the onboarding flow, and some shared components used in the Edit free listings page and Set up paid campaign page might be changed respectively.

Most requirements are listed in pcTzPl-Kc-p2#the-flow-breakdown and the related Figma document. This list only outlines other changes besides the p2 post.

📌 Adjust the setting sections in the onboarding steps

• Merge the original step 3 into step 2 - Free Listings + Paid Ads: Combine the audience and shipping steps #1616
• Remove the auto-fill mechanism of shipping rates - Free Listings + Paid Ads: Combine the audience and shipping steps #1616
• Add another submit button to step 4 for skipping paid ads creation - Free Listings + Paid Ads: Add step 4 to the onboarding flow #1619

📌 Update other UI changes

Refer to Landing Page, Step 1: Set up accounts, Step 2: Configure product listings, Step 3: Confirm store requirements, and Submission Success in pcTzPl-Kc-p2#the-flow-breakdown

• Logo icons in some account cards - Free Listings + Paid Ads: UI updates for get started page and onboarding flow #1618
• Layouts and copywriting on the landing page - Free Listings + Paid Ads: UI updates for get started page and onboarding flow #1618
• Layouts and copywriting of steps 1~3 in the onboarding flow - Free Listings + Paid Ads: UI updates for get started page and onboarding flow #1618
• Add CSS disclaimer to step 1 - Free Listings + Paid Ads: Update learn more links, FAQs, CSS disclaimer, submission success modal, and title of free listings settings #1679
• FAQ card in step 4 - Free Listings + Paid Ads: Update learn more links, FAQs, CSS disclaimer, submission success modal, and title of free listings settings #1679
• Submission success modal in the product feed page - Free Listings + Paid Ads: Update learn more links, FAQs, CSS disclaimer, submission success modal, and title of free listings settings #1679

📌 Product feed status section

Refer to Step 4.1: Setting up Paid Ads in pcTzPl-Kc-p2#the-flow-breakdown

• Implement this section UI - Free Listings + Paid Ads: Add the product feed status section UI #1638

📌 Boost product listings section

Refer to Card 2 in Step 4: Complete your campaign with paid ads in pcTzPl-Kc-p2#the-flow-breakdown

• Section UI and the interactions of "skip" and "continue" buttons - Free Listings + Paid Ads: Add the boost product listings section #1649
• Dynamically composite the ad previews - Free Listings + Paid Ads: Add the paid ads previews to the boost product listings section #1650

Site logo: https://wordpress.com/support/site-logo/

📌 Google Ads account section

Refer to Step 4.1: Setting up Paid Ads in pcTzPl-Kc-p2#the-flow-breakdown

• Add a button to disconnect Google Ads account - Free Listings + Paid Ads: Add the Google Ads account setup section #1654
• Add an external link to open Google's management page of connected Google Ads account - Free Listings + Paid Ads: Add the Google Ads account setup section #1654
• Handle the page redirection for the authorization of Google account - Free Listings + Paid Ads: Add the Google Ads account setup section #1654

📌 Ads audience and budget sections

Refer to Step 4.1: Setting up Paid Ads in pcTzPl-Kc-p2#the-flow-breakdown

• Tweak audience and budget UI - Free Listings + Paid Ads: Add the ads audience and budget sections #1655
• Handle the form data of campaign creation and forward it to the upper layer - Free Listings + Paid Ads: Add the ads audience and budget sections #1655

📌 Billing Ads card

Refer to Step 4.2: Set up Billing Ads in pcTzPl-Kc-p2#the-flow-breakdown

• Open a popup window for setting up billing, and the popup window should be resizable. - Free Listings + Paid Ads: Add the billing setup card and the paid ads completion #1677
• Card UI for notifying the successfully added billing method. - Free Listings + Paid Ads: Add the billing setup card and the paid ads completion #1677
• Add an alternative link for opening the billing setup page. - Free Listings + Paid Ads: Add the billing setup card and the paid ads completion #1677
• Complete the onboarding with paid ads setup. - Free Listings + Paid Ads: Add the billing setup card and the paid ads completion #1677

📌 Post-onboarding setup flow

• Add ad previews to the post-onboarding ads setup flow. - Free Listings + Paid Ads: Add ad previews to the post-onboarding ads setup flow #1721

📌 Client states management and API integration

• Fetch the number of products to be synced from a new API for the product feed status section - Free Listings + Paid Ads: Fetch the number of syncable products for the product feed status section #1706
• Fetch the product and site data from API for compositing the ad previews - Free Listings + Paid Ads: Use merchant's data to composite the ad previews #1692
• Store/restore the selected countries and the entered budget when leaving/entering step 4 - Free Listings + Paid Ads: Store and restore the states of paid ads setup #1683
• Store/restore the switched state of skipping or continuing the paid ads setup when leaving/entering step 4 - Free Listings + Paid Ads: Store and restore the states of paid ads setup #1683

📌 Event tracking

• Add event tracking - Free Listings + Paid Ads: Add event tracking #1689

• gla_onboarding_complete_button_click for A and C with these properties:
  • opened_paid_ads_setup: yes | no
  • google_ads_account_status: unknown | connected | disconnected | incomplete
  • billing_method_status: unknown | pending | approved | cancelled
  • campaign_form_validation: unknown | valid | invalid
  • The unknown status is used when the paid ads setup is not opened.
• gla_onboarding_open_paid_ads_setup_button_click for B
• gla_onboarding_complete_with_paid_ads_button_click for D

# Technical - Backend

# 📌 A new API for onboarding completed

In the previous onboarding flow the last API frontend calls is mc/settings/sync. It will set the timestamp to the option gla_mc_setup_completed_at. In the new onboarding flow, this API will be called again in step 4 to ensure all settings are updated if a merchant changes anything after they enter step 4 and then back to steps 13.~

We decide to create a new API mc/setup/complete and move the logic of setting the timestamp to the option gla_mc_setup_completed_at to this new API. (MC_SETUP_COMPLETED_AT in PHP code)

• Create a new API POST mc/setup/complete to set the timestamp to the option gla_mc_setup_completed_at.
  • Payload: No payload
  • Response:
    • Status: 201 Created
    • Data: No data
• In the API mc/settings/sync, do not set the timestamp to the option gla_mc_setup_completed_at.

# 📌 Extends mc/product-statistics API to return # of syncable products

In the step 4 of the new onboarding flow, we will display Your product listings are ready to be uploaded • # products on the first card. The # in the wording is the number of products that are ready to be synced. After some discussion on the project post (pcTzPl-I1-p2#comment-1604) we decide the extend an existing API mc/product-statistics and return a new data syncable_products in the response data. We can reuse an existing method find_sync_ready_products in src/Product/ProductRepository.phpWe will create two new APIs, GET mc/syncable-products-count and POST mc/syncable-products-count for this requirement.

• In API mc/product-statistics, modify the logic to return the following new data:

  {
      "timestamp": null,
      "statistics": null,
      "scheduled_sync": 0,
      "syncable_products": 29
  }

• Revisit the logic of display product overview in the GLA product feed page. The sum of the products there should be the number of syncable products, rather the number of total products in WooCommerce.

# 📌 Syncable Products Count

In the step 4 of the new onboarding flow, we will display Your product listings are ready to be uploaded • # products on the first card. The # in the wording is the number of products that are ready to be synced. We will create two new APIs, GET mc/syncable-products-count and POST mc/syncable-products-count for this requirement.

• New API to retrieve the number of syncable products: GET mc/syncable-products-count - Free Listings + Paid Ads: Add two APIs to retrieve the syncable products count and schedule the job to calculate the count #1699
  • If there are data in the database:

    {
        "count": 20
    }

  • If there are no data or the data are not yet ready in the database, return null:

    {
        "count": null
    }

• New API to schedule a job to calculate the number of syncable products: POST mc/syncable-products-count
  • No parameters required. - Free Listings + Paid Ads: Add two APIs to retrieve the syncable products count and schedule the job to calculate the count #1699
  • ✏️ Frontend should call it right after the user enters the onboarding flow.
• Group variation products as one for the same parents when counting syncable products. - Free Listings + Paid Ads: Group variations type for syncable products #1713
• Revisit the logic of display product overview in the GLA product feed page. The sum of the products there should be the number of syncable products, rather the number of total products in WooCommerce. - Fix incorrect product statistics count #1728
  • This is a follow-up issue so it can be excluded in the first release of this project.

# 📌 Verify all the logics depend on gla_ads_setup_completed_at

Frontend will call the API ads/setup/complete if merchants set up Paid Ads in step 4, and this API will set the timestamp to the option gla_ads_setup_completed_at. (ADS_SETUP_COMPLETED_AT in PHP code)

• Verify all the logics depend on gla_ads_setup_completed_at, update code if needed.

# 📌 Update the step name logic returned by the API mc/setup

Since some of the steps in the new onboarding flow are changed in order or merged together.

• Update the step name logic returned by the API mc/setup. Free Listings + Paid Ads: Add step 4 to the onboarding flow #1619

# 📌 Return merchants key product data (e.g. bestselling)

If we aim at returning the bestselling product, we don’t need to add a new API for it. Instead, we can extend the existing API mc/product-feed and doing some extra meta query to get the product that has largest total sales. However, we would need to add extra returned data such as product image and price for the API mc/product-feed. More information can be found in pcTzPl-I1-p2#comment-1533.

• Extend mc/product-feed API to be able to filter the bestselling product - Free Listings + Paid Ads: Update product feed API to return the bestselling product #1681
  • New value total_sales for the query parameter orderby.
  • Use parameters per_page=1, orderby=total_sales, and order=desc to get the bestselling product.

Example:

// GET mc/product-feed?per_page=1&orderby=total_sales&order=desc

{
    "products": [
        {
            "id": 279,
            "title": "Product title",
            "visible": true,
            "status": "disapproved",
            "errors": [],
            "price": "10", // new data
            "image_url": "https://example.com/example.png", // new data
        }
    ],
    "total": 28,
    "page": "1"
}

• Add siteLogoUrl into glaData for frontend to use - Free Listings + Paid Ads: Update product feed API to return the bestselling product #1681

Frontend needs to display the site logo, instead of putting it in product-feed AP, it's more appropriate to add it in glaData.siteLogoUrl.

Example on how to get the custom site logo url:

wp_get_attachment_image_url( get_theme_mod( 'custom_logo' ), 'full' );

Note that if the site admin does not upload a custom site logo, the above code will return false.
In glaData.siteLogoUrl it will be null.

Links

Project:

• Project thread: pcTzPl-I1-p2
• Design thread: pcTzPl-Kc-p2

Figma:

• fqR0EHi63lWahRcVTKCcba-fi-4%3A36753

[nikivias]

Hello hello, we need to do a small update to Step 1 (Connect accounts) of the FL+ Ads flow. Please see the original conversation here

The update is to add a CSS disclaimer on the said step/page. As per Google: "Our requirement is that platform’s UI should include instructions on how to work with a third-party Comparison Shopping Service early in the onboarding flow. We have flexibility with the language, as long as it is clear to merchants."

The change has been added into the design on Figma

@eason9487