From d6d6eaee188297182fafe4cdd8f9e22bc500069f Mon Sep 17 00:00:00 2001 From: Dilan Perera <39415471+RDPerera@users.noreply.github.com> Date: Thu, 19 Dec 2024 10:16:23 +0530 Subject: [PATCH 1/4] Update google-ads-overview.md --- .../connectors/google-ads-connector/google-ads-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/reference/connectors/google-ads-connector/google-ads-overview.md b/en/docs/reference/connectors/google-ads-connector/google-ads-overview.md index 8dc0202ac..946e8b10a 100644 --- a/en/docs/reference/connectors/google-ads-connector/google-ads-overview.md +++ b/en/docs/reference/connectors/google-ads-connector/google-ads-overview.md @@ -12,7 +12,7 @@ To see the Google Ads Connector, go to the [WSO2 Connector Store](https://store. | Connector version | Supported product versions | | ------------- |-------------| -| 1.0.2 | MI 4.3.0 | +| 1.1.0 | MI 4.3.0 | ## Google Ads Connector documentation From 85b7c7a0a7038af8e57fdd056c42cfd841c22c82 Mon Sep 17 00:00:00 2001 From: Dilan Perera <39415471+RDPerera@users.noreply.github.com> Date: Thu, 19 Dec 2024 11:41:34 +0530 Subject: [PATCH 2/4] Update google-ads-configuration.md --- .../google-ads-configuration.md | 395 ++++++++++++++++-- 1 file changed, 354 insertions(+), 41 deletions(-) diff --git a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md index 329d8c4dd..9d9493ca4 100644 --- a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md +++ b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md @@ -918,43 +918,143 @@ To use the Google Ads connector, first create the connection with your configura } ``` -??? note "uploadUserData" - The `uploadUserData` operation uploads the given user data. +??? note "userListsMutate" + The `userListsMutate` operation creates or updates user lists. Operation statuses are returned. - + - + - + - - + + + + + + +
Parameter Name Description Required
customerIdRequired. The ID of the customer for which to update the user data.Required. The ID of the customer whose user lists are being modified. Yes
operationsThe list of operations to perform on individual ads. Type: [UserDataOperation](https://developers.google.com/google-ads/api/rest/reference/rest/v17/customers/uploadUserData#UserDataOperation) object.Required. The list of operations to perform on individual user lists. Type: [UserListOperation](https://developers.google.com/google-ads/api/rest/reference/rest/v17/UserListOperation) object. Yes
customerMatchUserListMetadataMetadata for data updates to a Customer Match user list. Type: [CustomerMatchUserListMetadata](https://developers.google.com/google-ads/api/rest/reference/rest/v17/CustomerMatchUserListMetadata) object.partialFailureIf true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false.No
validateOnlyIf true, the request is validated but not executed. Only errors are returned, not results. No
- + **Sample configuration** ```xml - + {json-eval($.customer_id)} {json-eval($.operations)} - {json-eval($.customerMatchUserListMetadata)} - + ``` **Sample request** + ```json + { + "customer_id": "123123123", + "operations": [ + { + "create": { + "name": "My Customer Match List", + "description": "List created via MI", + "membershipLifeSpan": 30, + "crmBasedUserList": { + "uploadKeyType": "CONTACT_INFO", + "dataSourceType": "FIRST_PARTY" + } + } + } + ] + } + ``` + +??? note "uploadUserData" + The `uploadUserData` operation adds or removes users from user lists. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter NameDescriptionRequired
customerIdRequired. The ID of the customer whose user lists are being modified.Yes
userListIdRequired. The ID of the user list whose users are being modified.Yes
dataSourceTypeRequired. Defines the data source for the user list. Options: +
    +
  • From a Google Ads API request — Enables the previous operation parameters.
    • +
  • From a JSON array — Activates attributes for uploading user data as a JSON array.
    • +
+ 		Yes
operationsThe list of operations to perform on individual user lists. Type: [UserListOperation](https://developers.google.com/google-ads/api/rest/reference/rest/v17/UserListOperation) object.Required if dataSourceType is From a Google Ads API request
jsonArrayContentA JSON array containing user data to upload.Required if dataSourceType is From a JSON array
operationTypeDefines the operation to be performed on the user list. Options: create or remove. Required if dataSourceType is From a JSON array
userIdentifierSourceSpecifies the source of the user identifiers. Options: UNKNOWN, UNSPECIFIED, FIRST_PARTY or THIRD_PARTY.No
transactionAttributesAllows the inclusion of transaction attributes for user data upload.No
userAttributesIncludes additional user attributes for the uploaded data.No
consentIndicates consent for uploading user data.No
+ + **Sample configuration for "From a Google Ads API request"** + + ```xml + + {json-eval($.customer_id)} + {json-eval($.operations)} + {json-eval($.userListId)} + + ``` + + **Sample request for "From a Google Ads API request"** + ```json { "customer_id": "123123123", @@ -966,55 +1066,280 @@ To use the Google Ads connector, first create the connection with your configura "hashedEmail": "2c41b9d011bc28e71842637075e2a67cf4e73010172f4a18985494467d73a6d6" }, { - "hashedEmail": "00b340221ad566a1400936daadce44a7c61b5b04505fc66d3d55d96bde434bc1" + "hashedPhoneNumber": "00b340221ad566a1400936daadce44a7c61b5b04505fc66d3d55d96bde434bc1" } ] } } ], - "customerMatchUserListMetadata": { - "userList": "customers/123123123/userLists/8827689117" - } + "userListId": "1232132321" } ``` -??? note "userListsMutate" - The `userListsMutate` operation creates or updates user lists. Operation statuses are returned. + **Sample configuration for "From a JSON array"** + + ```xml + + {json-eval($.customer_id)} + From a JSON array + {json-eval($.jsonArrayContent)} + create + UNSPECIFIED + {json-eval($.userListId)} + + ``` + + **Sample request for "From a JSON array"** + + ```json + { + "customer_id": "123123123", + "jsonArrayContent": [ + {"phoneNumber": "+94112132234"}, + {"email": "someone@sample.com"}, + {"mobileId": "23131234324"} + ], + "userListId": "1232132321" + } + ``` + + **Acceptance Criteria for `jsonArrayContent`** + + To upload a user list, the input must be a JSON array containing any number of user objects. Each user object represents a single user identifier. Below is the format and guidelines for creating and uploading the user list. + + **Example Format:** + ```json + [ + {"user_identifier1": "value1"}, + {"user_identifier2": "value2"}, + {"user_identifier3": "value3"} + ] + ``` + + **User Identifier Types:** + Each user object must contain only one of the following user identifiers: + - **Phone Number** + ```json + {"phoneNumber": "+94112132234"} + ``` + - **Email Address** + ```json + {"email": "someone@sample.com"} + ``` + - **Mobile ID** + ```json + {"mobileId": "23131234324"} + ``` + - **Third-Party User ID** + ```json + {"thirdPartyUserId": "2124234234"} + ``` + - **Address Information** + ```json + { + "addressInfo": { + "firstName": "Someone", + "lastName": "Someone", + "city": "somecity", + "state": "aa", + "countryCode": "aa", + "postalCode": "12345", + "streetAddress": "SampleRd" + } + } + ``` + + **Additional Field: `userIdentifierSource`** + Each user object can optionally include a `userIdentifierSource` field with one of the following values: + - `FIRST_PARTY`: User identifier provided by the advertiser. + - `THIRD_PARTY`: User identifier provided by a partner. + + **Example:** + ```json + {"userIdentifierSource": "FIRST_PARTY", "phoneNumber": "0772345164"} + ``` + + ** Notes:** + - Each user object must contain **only one user identifier**. Multiple identifiers in the same object are treated as separate user objects. + - Example of incorrect format: + ```json + { + "Email": "someone@abc.com", + "Phone": "0893425678" + } + ``` + This will be treated as: + ```json + [ + {"email": "someone@abc.com"}, + {"phoneNumber": "0893425678"} + ] + ``` + +??? note "getCustomers" + The `getCustomers` operation returns all customers. - + - + - - + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter NameParameter name Description Required
customerIdRequired. The ID of the customer whose user lists are being modified.The ID of the customer being queried. Type: string Yes
operationsRequired. The list of operations to perform on individual user lists. Type: [UserListOperation](https://developers.google.com/google-ads/api/rest/reference/rest/v17/UserListOperation) object.pageTokenToken of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: stringNo
pageSizeNumber of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integerNo
validateOnlyIf true, the request is validated but not executed. Type: booleanNo
returnTotalResultsCountIf true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: booleanNo
summaryRowSettingDetermines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: [SummaryRowSetting](https://developers.google.com/google-ads/api/rest/reference/rest/v17/SummaryRowSetting) enumNo
+ + **Sample configuration** + + ```xml + + {json-eval($.customer_id)} + + ``` + + **Sample request** + + ```json + { + "customer_id": "123123123" + } + ``` + +??? note "getCampaigns" + The `getCampaigns` operation returns all campaigns. + + + + + + + + + - - + + + + + + + - + + + + + + + + + + +
Parameter nameDescriptionRequired
customerIdThe ID of the customer being queried. Type: string Yes
partialFailureIf true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false.pageTokenToken of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: stringNo
pageSizeNumber of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integer No
validateOnlyIf true, the request is validated but not executed. Only errors are returned, not results.If true, the request is validated but not executed. Type: booleanNo
returnTotalResultsCountIf true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: booleanNo
summaryRowSettingDetermines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: [SummaryRowSetting](https://developers.google.com/google-ads/api/rest/reference/rest/v17/SummaryRowSetting) enum No
- + **Sample configuration** ```xml - + {json-eval($.customer_id)} - {json-eval($.operations)} - + + ``` + + **Sample request** + + ```json + { + "customer_id": "123123123" + } + ``` + +??? note "getUserLists" + The `getUserLists` operation returns all user lists. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameDescriptionRequired
customerIdThe ID of the customer being queried. Type: stringYes
userListNameThe name of the user list to retrieve. Type: stringNo
pageTokenToken of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: stringNo
pageSizeNumber of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integerNo
validateOnlyIf true, the request is validated but not executed. Type: booleanNo
returnTotalResultsCountIf true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: booleanNo
summaryRowSettingDetermines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: [SummaryRowSetting](https://developers.google.com/google-ads/api/rest/reference/rest/v17/SummaryRowSetting) enumNo
+ + **Sample configuration** + + ```xml + + {json-eval($.customer_id)} + {json-eval($.user_list_name)} + ``` **Sample request** @@ -1022,19 +1347,7 @@ To use the Google Ads connector, first create the connection with your configura ```json { "customer_id": "123123123", - "operations": [ - { - "create": { - "name": "My Customer Match List", - "description": "List created via MI", - "membershipLifeSpan": 30, - "crmBasedUserList": { - "uploadKeyType": "CONTACT_INFO", - "dataSourceType": "FIRST_PARTY" - } - } - } - ] + "user_list_name": "My User List" } ``` From d7820be6a3a1eec57cb5c8325ae5d92bdc0a674b Mon Sep 17 00:00:00 2001 From: Dilan Perera <39415471+RDPerera@users.noreply.github.com> Date: Fri, 20 Dec 2024 10:32:28 +0530 Subject: [PATCH 3/4] Update google-ads-configuration.md --- .../google-ads-configuration.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md index 9d9493ca4..478adbf81 100644 --- a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md +++ b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md @@ -970,7 +970,7 @@ To use the Google Ads connector, first create the connection with your configura "membershipLifeSpan": 30, "crmBasedUserList": { "uploadKeyType": "CONTACT_INFO", - "dataSourceType": "FIRST_PARTY" + "": "FIRST_PARTY" } } } @@ -997,11 +997,11 @@ To use the Google Ads connector, first create the connection with your configura Yes - dataSourceType + inputStructure Required. Defines the data source for the user list. Options: Yes @@ -1009,17 +1009,17 @@ To use the Google Ads connector, first create the connection with your configura operations The list of operations to perform on individual user lists. Type: [UserListOperation](https://developers.google.com/google-ads/api/rest/reference/rest/v17/UserListOperation) object. - Required if dataSourceType is From a Google Ads API request + Required if inputStructure is GOOGLE_API_COMPATIBLE jsonArrayContent A JSON array containing user data to upload. - Required if dataSourceType is From a JSON array + Required if inputStructure is JSON_ARRAY operationType Defines the operation to be performed on the user list. Options: create or remove. - Required if dataSourceType is From a JSON array + Required if inputStructure is JSON_ARRAY userIdentifierSource @@ -1043,7 +1043,7 @@ To use the Google Ads connector, first create the connection with your configura - **Sample configuration for "From a Google Ads API request"** + **Sample configuration for "GOOGLE_API_COMPATIBLE"** ```xml @@ -1053,7 +1053,7 @@ To use the Google Ads connector, first create the connection with your configura ``` - **Sample request for "From a Google Ads API request"** + **Sample request for "GOOGLE_API_COMPATIBLE"** ```json { @@ -1076,12 +1076,12 @@ To use the Google Ads connector, first create the connection with your configura } ``` - **Sample configuration for "From a JSON array"** + **Sample configuration for "JSON_ARRAY"** ```xml {json-eval($.customer_id)} - From a JSON array + JSON_ARRAY {json-eval($.jsonArrayContent)} create UNSPECIFIED @@ -1089,7 +1089,7 @@ To use the Google Ads connector, first create the connection with your configura ``` - **Sample request for "From a JSON array"** + **Sample request for "JSON_ARRAY"** ```json { From c63963b7da555cc929473a2ae19d823c797df795 Mon Sep 17 00:00:00 2001 From: Dilan Perera <39415471+RDPerera@users.noreply.github.com> Date: Fri, 20 Dec 2024 13:26:34 +0530 Subject: [PATCH 4/4] Update google-ads-configuration.md --- .../google-ads-connector/google-ads-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md index 478adbf81..a6c2487d7 100644 --- a/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md +++ b/en/docs/reference/connectors/google-ads-connector/google-ads-configuration.md @@ -978,8 +978,8 @@ To use the Google Ads connector, first create the connection with your configura } ``` -??? note "uploadUserData" - The `uploadUserData` operation adds or removes users from user lists. +??? note "userDataMutate" + The `userDataMutate` operation adds or removes users from user lists.
Parameter Name