Facebook Marketing API implementation (ads management + ads insights)

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/FacebookErrors.java

@@ -194,7 +194,10 @@ public class FacebookErrors {
 	public static final int POKE_OUTSTANDING = 511;
 	public static final int POKE_RATE = 512;
 	public static final int POKE_USER_BLOCKED = 513;
-
+
+	// Rate limiting errors
+	public static final int USER_APP_TOO_MANY_CALLS = 613;
+
 	// Ref errors
 	public static final int REF_SET_FAILED = 700;
 
@@ -304,6 +307,9 @@ public class FacebookErrors {
 	public static final int TEST_ACCOUNTS_INVALID_ID = 2901;
 	public static final int TEST_ACCOUNTS_CANT_REMOVE_APP = 2902;
 	public static final int TEST_ACCOUNTS_CANT_DELETE = 2903;
+
+	// Ad Level Rate Limit error
+	public static final int AD_CREATION_LIMIT_EXCEEDED = 1487225;
 
 	public static boolean isGeneralError(int code) {
 		return code < 100;

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/GraphApi.java

@@ -131,7 +131,16 @@ public interface GraphApi {
 	 * @param data the data to publish to the connection.
 	 */
 	void post(String objectId, String connectionName, MultiValueMap<String, Object> data);
-
+
+	/**
+	 * Updates data of an object.
+	 * Requires appropriate permission to update to the object connection.
+	 * @param objectId the object ID to update.
+	 * @param data the data to update in the object.
+	 * @return true if update was successful
+	 */
+	boolean update(String objectId, MultiValueMap<String, Object> data);
+
 	/**
 	 * Deletes an object.
 	 * Requires appropriate permission to delete the object.

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/InvalidParameterException.java

@@ -0,0 +1,15 @@
+package org.springframework.social.facebook.api;
+
+import org.springframework.social.ApiException;
+
+/**
+ * Exception thrown when one of the supplied parameters is invalid.
+ *
+ * @author Sebastian G�recki
+ */
+public class InvalidParameterException extends ApiException {
+
+	public InvalidParameterException(String providerId, String message) {
+		super(providerId, message);
+	}
+}

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/ads/AccountOperations.java

@@ -0,0 +1,123 @@
+package org.springframework.social.facebook.api.ads;
+
+import org.springframework.social.ApiException;
+import org.springframework.social.InsufficientPermissionException;
+import org.springframework.social.MissingAuthorizationException;
+import org.springframework.social.facebook.api.PagedList;
+import org.springframework.social.facebook.api.ads.AdUser.AdUserRole;
+
+/**
+ * Defines operations for working with Facebook Marketing API Ad Account object.
+ *
+ * @author Sebastian G�recki
+ */
+public interface AccountOperations {
+
+	static final String[] AD_ACCOUNT_FIELDS = {
+			"id", "account_id", "account_status", "age", "amount_spent", "balance", "business_city", "business_country_code",
+			"business_name", "business_state", "business_street", "business_street2", "business_zip", "capabilities",
+			"created_time", "currency", "daily_spend_limit", "end_advertiser", "funding_source", "funding_source_details",
+			"is_personal", "media_agency", "name", "offsite_pixels_tos_accepted", "partner", "spend_cap", "timezone_id",
+			"timezone_name", "timezone_offset_hours_utc", "users", "tax_id_status"
+	};
+
+	static final String[] AD_ACCOUNT_INSIGHT_FIELDS = {
+			"account_id", "account_name", "date_start", "date_stop", "actions_per_impression", "clicks", "unique_clicks",
+			"cost_per_result", "cost_per_total_action", "cpc", "cost_per_unique_click", "cpm", "cpp", "ctr", "unique_ctr",
+			"frequency", "impressions", "unique_impressions", "objective", "reach", "result_rate", "results", "roas",
+			"social_clicks", "unique_social_clicks", "social_impressions", "unique_social_impressions", "social_reach",
+			"spend", "today_spend", "total_action_value", "total_actions", "total_unique_actions", "actions",
+			"unique_actions", "cost_per_action_type", "video_start_actions"
+	};
+
+	/**
+	 * Get all ad accounts for given user.
+	 *
+	 * @param userId the id of an user
+	 * @return the list of {@link AdAccount} objects
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	PagedList<AdAccount> getAdAccounts(String userId);
+
+	/**
+	 * Get the ad account by given id.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @return the {@link AdAccount} object
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	AdAccount getAdAccount(String accountId);
+
+	/**
+	 * Get all ad campaigns of an ad account.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @return the list of {@link AdCampaign} objects
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	PagedList<AdCampaign> getAdAccountCampaigns(String accountId);
+
+	/**
+	 * Get all users of the ad account.
+	 *
+	 * @param accountId the ID of the ad account, the string act_{ad_account_id}
+	 * @return the list of {@link AdUser} objects
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	PagedList<AdUser> getAdAccountUsers(String accountId);
+
+	/**
+	 * Add the user to the ad account.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @param userId    the id of an user (App Scoped User ID)
+	 * @param role      the role for the new user in ad account
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	void addUserToAdAccount(String accountId, String userId, AdUserRole role);
+
+	/**
+	 * Remove user's access to an ad account.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @param userId    the id of an user (App Scoped User ID)
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_management" permission.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 */
+	void deleteUserFromAdAccount(String accountId, String userId);
+
+	/**
+	 * Get the insight for the ad account in aggregate.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @return the {@link AdInsight} object
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 */
+	AdInsight getAdAccountInsight(String accountId);
+
+	/**
+	 * Updates the ad account with information given in adAccount object.
+	 * Currently only updates on ad account name and spend_cap are supported.
+	 *
+	 * @param accountId the ID of the ad account (account_id)
+	 * @param adAccount the ad account object containing updated account information
+	 * @return true if the update succeeded
+	 * @throws ApiException                    if there is an error while communicating with Facebook.
+	 * @throws MissingAuthorizationException   if FacebookAdsTemplate was not created with an access token.
+	 * @throws InsufficientPermissionException if the user has not granted "ads_read" or "ads_management" permission.
+	 */
+	boolean updateAdAccount(String accountId, AdAccount adAccount);
+}

spring-social-facebook/src/main/java/org/springframework/social/facebook/api/ads/Ad.java

@@ -0,0 +1,109 @@
+package org.springframework.social.facebook.api.ads;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+
+import java.util.Date;
+
+/**
+ * @author Sebastian G�recki
+ */
+public class Ad {
+	private String id;
+	private AdStatus status;
+	private String name;
+	private BidType bidType;
+	private BidInfo bidInfo;
+
+	private String accountId;
+	private String adSetId;
+	private String campaignId;
+
+	private String creativeId;
+	private Targeting targeting;
+
+	private Date createdTime;
+	private Date updatedTime;
+
+	public void setStatus(AdStatus status) {
+		this.status = status;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	public void setBidInfo(BidInfo bidInfo) {
+		this.bidInfo = bidInfo;
+	}
+
+	public void setAdSetId(String adSetId) {
+		this.adSetId = adSetId;
+	}
+
+	public void setCreativeId(String creativeId) {
+		this.creativeId = creativeId;
+	}
+
+	public String getId() {
+		return id;
+	}
+
+	public AdStatus getStatus() {
+		return status;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public BidType getBidType() {
+		return bidType;
+	}
+
+	public BidInfo getBidInfo() {
+		return bidInfo;
+	}
+
+	public String getAccountId() {
+		return accountId;
+	}
+
+	public String getAdSetId() {
+		return adSetId;
+	}
+
+	public String getCampaignId() {
+		return campaignId;
+	}
+
+	public String getCreativeId() {
+		return creativeId;
+	}
+
+	public Targeting getTargeting() {
+		return targeting;
+	}
+
+	public Date getCreatedTime() {
+		return createdTime;
+	}
+
+	public Date getUpdatedTime() {
+		return updatedTime;
+	}
+
+	public enum AdStatus {
+		ACTIVE, PAUSED, CAMPAIGN_PAUSED, CAMPAIGN_GROUP_PAUSED, CREDIT_CARD_NEEDED, DISABLED, DISAPPROVED, PENDING_REVIEW,
+		PREAPPROVED, PENDING_BILLING_INFO, ARCHIVED, DELETED, UNKNOWN;
+
+		@JsonCreator
+		public static AdStatus fromValue(String value) {
+			for (AdStatus status : AdStatus.values()) {
+				if (status.name().equals(value)) {
+					return status;
+				}
+			}
+			return UNKNOWN;
+		}
+	}
+}