Multichannel Marketing - API

[nima-karimi]

All Submissions:

• Have you followed the WooCommerce Contributing guideline?
• Does your code follow the WordPress' coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

This PR implements four new APIs for the marketing dashboard:

1. GET /wp-json/wc-admin/marketing/recommendations

Returns an array of recommended marketing channels and extensions. It accepts a category parameter that can be set to either channels or extensions.

This API obtains the list of recommended extensions from the GET https://woocommerce.com/wp-json/wccom/marketing-tab/1.2/recommendations.json API and filters the results based on their category and subcategories:

A) channels - Any recommended extension with the category of "marketing" and the subcategory of "sales-channel" will be included in the response.
B) extensions - Any recommended extension with the category of "marketing" but WITHOUT the subcategory of "sales-channel" will be included in the response. This means that the response will include the list of all marketing extensions and plugins recommended by the WooCommerce store API EXCEPT marketing channels.

The response schema is a mirror of WooCommerce.com's GET https://woocommerce.com/wp-json/wccom/marketing-tab/1.2/recommendations.json API.

2. GET /wp-json/wc-admin/marketing/channels

Returns an array of registered marketing channels.

Example Response:

[
    {
        "slug": "google-listings-and-ads",
        "is_setup_completed": true,
        "settings_url": "https://example.org/wp-admin/admin.php?page=wc-admin&path=/google/settings",
        "name": "Google Listings & Ads",
        "description": "Native integration with Google that allows merchants to easily display their products across Google’s network.",
        "product_listings_status": "synced",
        "errors_count": 0,
        "icon": "https://woocommerce.com/wp-content/uploads/2021/06/woo-GoogleListingsAds-jworee.png"
    }
]

3. GET /wp-json/wc-admin/marketing/campaigns

Returns an aggregated list of marketing campaigns for all registered marketing channels. This API returns a paginated response and accepts the following two parameters:

• page
• per_page

Example Response:

[
    {
        "id": "1",
        "channel": "google-listings-and-ads",
        "title": "11",
        "manage_url": "https://example.org/wp-admin/admin.php?page=wc-admin&path=/google/settings&subpath=/campaigns/edit",
        "cost": {
            "value": "100",
            "currency": "USD"
        }
    },
    {
        "id": "2",
        "channel": "google-listings-and-ads",
        "title": "22",
        "manage_url": "https://example.org/wp-admin/admin.php?page=wc-admin&path=/google/settings&subpath=/campaigns/edit",
        "cost": {
            "value": "200",
            "currency": "USD"
        }
    }
]

4. GET /wp-json/wc-admin/marketing/campaign-types

Returns an aggregated list of supported marketing campaign types for all registered marketing channels. Each marketing channel will provide this list by implementing the MarketingChannelInterface::get_supported_campaign_types method in their code base.

Example Response:

[
    {
        "id": "google-ads",
        "name": "Google Ads",
        "description": "Boost your product listings with a campaign that is automatically optimized to meet your goals.",
        "channel": {
            "slug": "google-listings-and-ads",
            "name": "Google Listings & Ads"
        },
        "create_url": "https://example.org/wp-admin/admin.php?page=wc-admin&path=/google/settings&subpath=/campaigns/create",
        "icon_url": "https://woocommerce.com/wp-content/uploads/2021/06/woo-GoogleListingsAds-jworee.png"
    }
]

Closes #34556.

How to test the changes in this Pull Request:

Before testing this PR, you must have at least one marketing channel installed and active on your store. Currently, we have only implemented the integration in the Google Listings & Ads extension (PR woocommerce/google-listings-and-ads#1730); therefore, to test this PR, you need to fetch the feature/mcm-integration branch of that extension and activate it on your store.

A. GET /wp-json/wc-admin/marketing/recommendations

1. Make a request to this endpoint and confirm you receive an error indicating that the category parameter is required.
2. Make another request with the category parameter set to channels and confirm only the marketing channel extensions are returned in the response. Marketing channels are extensions that have the sales-channel subcategory.
3. Make another request with the category parameter set to extensions and confirm all other marketing extensions are returned in the response EXCEPT marketing channels.

B. GET /wp-json/wc-admin/marketing/channels

1. Confirm that the Google Listings & Ads extension is active.
2. Send a request to this endpoint and confirm that details about the GLA channel are returned in the response.
3. Confirm that the values for is_setup_completed, errors_count, and product_listings_status are as they should be, depending on your setup.

C. GET /wp-json/wc-admin/marketing/campaigns

To test this endpoint, you must have at least one active marketing campaign defined in Google Listings & Ads. If not, we can mock some campaigns by modifying the GLAChannel.php file in Google Listings & Ads codebase and adding the following line right at the beginning of the GLAChannel::get_campaigns method:

return [
	new MarketingCampaign(
	'1',
	$this,
	'Test campaign',
	admin_url( 'admin.php?page=wc-admin&path=/google/settings&subpath=/campaigns/edit' ),
	new Price( '100', 'USD' ),
	),
];

This will return a marketing campaign when this endpoint is called.

1. Confirm that the Google Listings & Ads extension is active and you have at least one active marketing campaign (or add the code above to return a mock campaign).
2. Send a request to this endpoint and confirm that the campaign details are correct.

D. GET /wp-json/wc-admin/marketing/campaign-types

1. Confirm that the Google Listings & Ads extension is active.
2. Send a request to this endpoint and confirm that details about the Google Ads campaign type are returned in the response.
3. Confirm that the create_url link works and points to the campaign create page of GLA.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you created a changelog file for each project being changed, ie pnpm --filter=<project> changelog add?

FOR PR REVIEWER ONLY:

• I have reviewed that everything is sanitized/escaped appropriately for any SQL or XSS injection possibilities. I made sure Linting is not ignored or disabled.

[github-actions]

Test Results Summary

Commit SHA: c6ba33e

Test 🧪	Passed ✅	Failed 🚨	Broken 🚧	Skipped ⏭️	Unknown ❔	Total 📊	Duration ⏱️
API Tests	259	0	0	2	0	261	0m 52s
E2E Tests	189	0	0	6	0	195	14m 37s

---

To view the full API test report, click here.
To view the full E2E test report, click here.
To view all test reports, visit the WooCommerce Test Reports Dashboard.

[nima-karimi]

Update:

I've added another API to this PR to fetch the list of supported marketing campaign types (GET /wp-json/wc-admin/marketing/campaign-types).

Along with this API, a new method is added to the MarketingChannelInterface called get_supported_campaign_types. Each channel will implement this method in its code base and return an array of MarketingCampaignType objects. The MarketingCampaignType class represents a campaign type supported by each channel, such as Google Ads or Pinterest Ads.

[layoutd]

Testing went well except for a small issue in the tests, and one deprecation notice (due to using PHP 8.1 🔮):

GET wp-json/wc-admin/marketing/campaigns

<b>Deprecated</b>:  Return type of Automattic\WooCommerce\Admin\Marketing\Price: :jsonSerialize() should either be compatible with JsonSerializable: :jsonSerialize(): mixed, or the #[\ReturnTypeWillChange
] attribute should be used to temporarily suppress the notice in <b>/var/www/html/wp-content/plugins/woocommerce-monorepo/plugins/woocommerce/src/Admin/Marketing/Price.php</b> on line <b>64</b>

I also noticed the the campaign URLs returned for Google Listings & Ads are incorrect (commented in woocommerce/google-listings-and-ads#1730)

[layoutd]

The MarketingCampaign::get_channel method doesn't exist anymore (8ef6532). Looks like it would need to be changed to get_type, which would have to return a mocked MarketingCampaignType.

This doesn't seem to affect the assertions in this test, though.

[nima-karimi]

Oops missed that one! Fixed in c6ba33e

[nima-karimi]

Thanks for the review Justin. I removed the jsonSerialize from the Price class since it wasn't being used and now the php8.1 deprecation notice should be gone. The issue with GLA integration is also fixed in its PR.

[ecgan]

3. GET /wp-json/wc-admin/marketing/campaigns

@nima-karimi , I noticed that the campaigns API response data does not have a "summary description" for the campaigns.

The following screenshot is the figma design for your reference, where we have short, dynamic descriptions for different campaigns:

I suppose this can be done in future iterations.

[ecgan]

3. GET /wp-json/wc-admin/marketing/campaigns

[...] This API returns a paginated response and accepts the following two parameters:

• page
• per_page

Example Response:

@nima-karimi , we need to have a "total number of rows" or "total number of pages" in the API response so that we can display total number of pages (i.e. "Page 1 of 2") in the pagination UI.

For now, I will code in a large enough per_page value to get "all" the campaigns in one request.

[nima-karimi]

@ecgan

we need to have a "total number of rows" or "total number of pages" in the API response so that we can display total number of pages (i.e. "Page 1 of 2") in the pagination UI.

Oh, sorry should've mentioned this in the descriptions, but the following HTTP response headers already provide this info:

• X-WP-Total - The total number of campaigns
• X-WP-TotalPages - Total number of pages

Other WooCommerce endpoints are also using these headers to render this information, but let me know if it'd be easier to have these in the JSON response.

[ecgan]

the following HTTP response headers already provide this info:

• X-WP-Total - The total number of campaigns
• X-WP-TotalPages - Total number of pages

@nima-karimi , I thought I looked into the response headers too but I guess I missed it 😂 Thanks for the info, I'll use that then. 👍