Adding support to WhatsApp events on Business SDK

Summary:
CAPI CTWA has been launched to 100% since November 2023, but is still not supported in our Meta Business SDK.

This diff adds support for WhatsApp events on the Business SDK. It includes changes to the Event class to add a new field for the messaging channel, as well as changes to the ServerSideApiConstants class to include new constants for the CTWA_CLID and PAGE_ID parameters.

 Additionally, there are changes to the ActionSource class to include a new value for business messaging, and changes to the UserData class to include new fields for the CTWA_CLID and PAGE_ID parameters.

Files changed:

   sdk/servers/java/release/src/main/java/com/facebook/ads/sdk/serverside/ActionSource.java
   sdk/servers/java/release/src/main/java/com/facebook/ads/sdk/serverside/Event.java
   sdk/servers/java/release/src/main/java/com/facebook/ads/sdk/serverside/MessagingChannel.java
   sdk/servers/java/release/src/main/java/com/facebook/ads/sdk/serverside/UserData.java
   codegen/templates/java/src/main/java/com/facebook/ads/utils/ServeSideApiConstants.java
   sdk/servers/java/release/src/main/java/com/facebook/ads/utils/ServerSideApiConstants.java

Other files changes are because of codegen script

Reviewed By: stcheng

Differential Revision: D53941503

fbshipit-source-id: f54f634050b5f008e5d72f817b27092535315ccf

src/main/java/com/facebook/ads/sdk/serverside/ActionSource.java

@@ -59,6 +59,11 @@ public enum ActionSource {
    */
   system_generated,
 
+  /**
+   * Conversion happened through a business messaging channel, such as WhatsApp or Instagram Direct.
+   */
+  business_messaging,
+
   /**
    * Conversion happened in a way that is not listed.
    */

src/main/java/com/facebook/ads/sdk/serverside/Event.java

@@ -64,6 +64,9 @@ public class Event {
   @SerializedName("advanced_measurement_table")
   private String advancedMeasurementTable = null;
 
+  @SerializedName("messaging_channel")
+  private MessagingChannel messagingChannel = null;
+
   /**
    * Default Constructor.
    */
@@ -86,11 +89,12 @@ public Event() {
    * @param actionSource Where the conversion occurred.
    * @param appData AppData object that contains app data and device information
    * @param advancedMeasurementTable Only used for Advanced Measurement in the Advanced Analytics product.
+   * @param messagingChannel indicated the messaging channel used.
    */
   public Event(String eventName, Long eventTime, String eventSourceUrl, Boolean optOut,
       String eventId, UserData userData, CustomData customData, String[] dataProcessingOptions,
       Integer dataProcessingOptionsCountry, Integer dataProcessingOptionsState, ActionSource actionSource, AppData appData,
-      String advancedMeasurementTable) {
+      String advancedMeasurementTable, MessagingChannel messagingChannel) {
     this.eventName = eventName;
     this.eventTime = eventTime;
     this.eventSourceUrl = eventSourceUrl;
@@ -104,6 +108,7 @@ public Event(String eventName, Long eventTime, String eventSourceUrl, Boolean op
     this.actionSource = actionSource;
     this.appData = appData;
     this.advancedMeasurementTable = advancedMeasurementTable;
+    this.messagingChannel = messagingChannel;
   }
 
   /**
@@ -498,6 +503,35 @@ public void setAdvancedMeasurementTable(String advancedMeasurementTable) {
     this.advancedMeasurementTable = advancedMeasurementTable;
   }
 
+  /**
+   * Set messagingChannel for the event.
+   *
+   * @param messagingChannel represents where the conversation occurred.
+   * @return Event
+   */
+  public Event messagingChannel(MessagingChannel messagingChannel) {
+    this.messagingChannel = messagingChannel;
+    return this;
+  }
+
+  /**
+   * Get messagingChannel for the event.
+   *
+   * @return messagingChannel
+   */
+  public MessagingChannel getMessagingChannel() {
+    return messagingChannel;
+  }
+
+  /**
+   * Set messagingChannel for the event.
+   *
+   * @param messagingChannel represents where the conversation occurred.
+   */
+  public void setMessagingChannel(MessagingChannel messagingChannel) {
+    this.messagingChannel = messagingChannel;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -516,13 +550,14 @@ public boolean equals(Object o) {
         && Objects.equals(this.customData, event.customData)
         && Objects.equals(this.dataProcessingOptions, event.dataProcessingOptions)
         && Objects.equals(this.dataProcessingOptionsCountry, event.dataProcessingOptionsCountry)
-        && Objects.equals(this.dataProcessingOptionsState, event.dataProcessingOptionsState);
+        && Objects.equals(this.dataProcessingOptionsState, event.dataProcessingOptionsState)
+        && Objects.equals(this.messagingChannel, event.messagingChannel);
   }
 
   @Override
   public int hashCode() {
     return Objects.hash(
-        eventName, eventTime, eventSourceUrl, optOut, eventId, userData, customData, dataProcessingOptions, dataProcessingOptionsCountry, dataProcessingOptionsState);
+        eventName, eventTime, eventSourceUrl, optOut, eventId, userData, customData, dataProcessingOptions, dataProcessingOptionsCountry, dataProcessingOptionsState , messagingChannel);
   }
 
   @Override
@@ -540,6 +575,7 @@ public String toString() {
     sb.append("    dataProcessingOptions: ").append(toIndentedString(dataProcessingOptions)).append("\n");
     sb.append("    dataProcessingOptionsCountry: ").append(toIndentedString(dataProcessingOptionsCountry)).append("\n");
     sb.append("    dataProcessingOptionsState: ").append(toIndentedString(dataProcessingOptionsState)).append("\n");
+    sb.append("    messagingChannel: ").append(toIndentedString(messagingChannel)).append("\n");
     sb.append("}");
     return sb.toString();
   }

src/main/java/com/facebook/ads/sdk/serverside/MessagingChannel.java

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc. All rights reserved.
+ *
+ * <p>You are hereby granted a non-exclusive, worldwide, royalty-free license to use, copy, modify,
+ * and distribute this software in source code or binary form for use in connection with the web
+ * services and APIs provided by Facebook.
+ *
+ * <p>As with any software that integrates with the Facebook platform, your use of this software is
+ * subject to the Facebook Developer Principles and Policies [http://developers.facebook.com/policy/].
+ * This copyright notice shall be included in all copies or substantial portions of the software.
+ *
+ * <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.facebook.ads.sdk.serverside;
+
+/**
+ * Used to specify which messaging channel was used.
+ * See https://developers.facebook.com/docs/marketing-api/conversions-api/business-messaging
+ */
+public enum MessagingChannel {
+
+  /**
+   * Conversation happened on Instagram Direct.
+   */
+  instagram,
+
+  /**
+   * Conversation happened on Messenger.
+   */
+  messenger,
+
+  /**
+   * Conversation happened on WhatsApp.
+   */
+  whatsapp,
+}

src/main/java/com/facebook/ads/sdk/serverside/UserData.java

@@ -131,6 +131,12 @@ public class UserData {
   @SerializedName(ServerSideApiConstants.ANONYMOUS_ID)
   private String anonId = null;
 
+  @SerializedName(ServerSideApiConstants.CTWA_CLID)
+  private String ctwaClid = null;
+
+  @SerializedName(ServerSideApiConstants.PAGE_ID)
+  private String pageId = null;
+
   /**
    * Default Constructor.
    */
@@ -166,12 +172,14 @@ public UserData() {
    * @param doby Date of birth year
    * @param madid Mobile Advertiser ID
    * @param anonId ID of a person who has installed the app anonymously
+   * @param ctwaClid ID of a conversation that was started on WhatsApp
+   * @param pageId ID of the page that the ad is associated with
    */
   public UserData(String email, String phone, GenderEnum gender, String dateOfBirth,
       String lastName, String firstName, String city, String state, String zipcode,
       String countryCode, String externalId, String clientIpAddress, String clientUserAgent,
       String fbc, String fbp, String subscriptionId, String fbLoginId, String leadId,
-      String f5first, String f5last, String fi, String dobd, String dobm, String doby, String madid, String anonId) {
+      String f5first, String f5last, String fi, String dobd, String dobm, String doby, String madid, String anonId, String ctwaClid, String pageId) {
     this.emails = Arrays.asList(email);
     this.phones = Arrays.asList(phone);
     this.genders = Arrays.asList(gender);
@@ -1395,6 +1403,64 @@ public void setAnonId(String anonId) {
     this.anonId = anonId;
   }
 
+  /**
+   * Get the ctwaClid of the conversation that was started on WhatsApp
+   *
+   * @param ctwaClid the anonymous id
+   * @return UserData
+   */
+  public UserData ctwaClid(String ctwaClid) {
+    setCtwaClid(ctwaClid);
+    return this;
+  }
+
+  /**
+   * ctwaClid of the conversation that was started on WhatsApp
+   *
+   * @return ctwaClid
+   */
+  public String getCtwaClid() {
+    return this.ctwaClid;
+  }
+
+  /**
+   * Set the ctwaClid of the conversation that was started on WhatsApp
+   *
+   * @param ctwaClid the anonymous Id
+   */
+  public void setCtwaClid(String ctwaClid) {
+    this.ctwaClid = ctwaClid;
+  }
+
+  /**
+   * Get the ID of the page that the ad is associated with
+   *
+   * @param pageId
+   * @return UserData
+   */
+  public UserData pageId(String pageId) {
+    setPageId(pageId);
+    return this;
+  }
+
+  /**
+   * ID of the page that the ad is associated with
+   *
+   * @return pageId
+   */
+  public String getPageId() {
+    return this.pageId;
+  }
+
+  /**
+   * Set the ID of the page that the ad is associated with
+   *
+   * @param pageId
+   */
+  public void setPageId(String pageId) {
+    this.pageId = pageId;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -1429,7 +1495,9 @@ public boolean equals(Object o) {
         && Objects.equals(this.dobm, userData.dobm)
         && Objects.equals(this.doby, userData.doby)
         && Objects.equals(this.madid, userData.madid)
-        && Objects.equals(this.anonId, userData.anonId);
+        && Objects.equals(this.anonId, userData.anonId)
+        && Objects.equals(this.ctwaClid, userData.ctwaClid)
+        && Objects.equals(this.pageId, userData.pageId);
   }
 
   @Override
@@ -1460,7 +1528,9 @@ public int hashCode() {
         dobm,
         doby,
         madid,
-        anonId);
+        anonId,
+        ctwaClid,
+        pageId);
   }
 
   @Override
@@ -1494,6 +1564,8 @@ public String toString() {
     sb.append("    doby: ").append(toIndentedString(doby)).append("\n");
     sb.append("    madid: ").append(toIndentedString(madid)).append("\n");
     sb.append("    anonId: ").append(toIndentedString(anonId)).append("\n");
+    sb.append("    ctwaClid: ").append(toIndentedString(ctwaClid)).append("\n");
+    sb.append("    pageId: ").append(toIndentedString(pageId)).append("\n");
     sb.append("}");
     return sb.toString();
   }

src/main/java/com/facebook/ads/utils/ServerSideApiConstants.java

@@ -72,4 +72,8 @@ public class ServerSideApiConstants {
     public static final String MOBILE_ADVERTISER_ID = "madid";
 
     public static final String ANONYMOUS_ID = "anon_id";
+
+    public static final String CTWA_CLID = "ctwa_clid";
+
+    public static final String PAGE_ID = "page_id";
 }