Skip to content

Adding Retention Messaging API v1.3-4 changes #242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexanderjordanbaker merged 1 commit into from
Apr 22, 2026
Merged

Adding Retention Messaging API v1.3-4 changes #242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions src/main/java/com/apple/itunes/storekit/client/APIError.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,62 @@ public enum APIError {
*/
TRANSACTION_ID_IS_NOT_ORIGINAL_TRANSACTION_ID_ERROR(4000187L),

/**
* An error the API returns that indicates the performance test request is invalid.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/invalidperformancetestrequesterror">InvalidPerformanceTestRequestError</a>
*/
INVALID_PERFORMANCE_TEST_REQUEST(4000211L),

/**
* An error that indicates the request ID is invalid.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/invalidrequestiderror">InvalidRequestIdError</a>
*/
INVALID_REQUEST_ID(4000212L),

/**
* An error that indicates an error with an existing test.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/existingperformancetestrunerror">ExistingPerformanceTestRunError</a>
*/
EXISTING_PERFORMANCE_TEST_RUN(4000213L),

/**
* An error that indicates the URL is invalid.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/badrequestrealtimeurlerror">BadRequestRealtimeUrlError</a>
*/
BAD_REQUEST_REALTIME_URL(4000215L),

/**
* An error that indicates the image size provided is invalid.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/badrequestimagesizeerror">BadRequestImageSizeError</a>
*/
BAD_REQUEST_IMAGE_SIZE(4000216L),

/**
* An error that indicates there are too many bullet points.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/badrequesttoomanybulletpointserror">BadRequestTooManyBulletPointsError</a>
*/
BAD_REQUEST_TOO_MANY_BULLET_POINTS(4000218L),

/**
* An error that indicates the text for a bullet point is too long.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/badrequestbulletpointtexttoolongerror">BadRequestBulletPointTextTooLongError</a>
*/
BAD_REQUEST_BULLET_POINT_TEXT_TOO_LONG(4000219L),

/**
* An error that indicates that no image object is included, but the request indicates that the header should be placed above the image.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/badrequestaboveimagerequiresanimageerror">BadRequestAboveImageRequiresAnImageError</a>
*/
BAD_REQUEST_ABOVE_IMAGE_REQUIRES_AN_IMAGE(4000224L),

/**
* An error that indicates the subscription doesn't qualify for a renewal-date extension due to its subscription state.
*
Expand Down Expand Up @@ -412,6 +468,13 @@ public enum APIError {
*/
IMAGE_IN_USE(4030019L),

/**
* An error that indicates that passing a performance test is required before you can set a URL for the production environment.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/forbiddennopassingtesterror">ForbiddenNoPassingTestError</a>
*/
FORBIDDEN_NO_PASSING_TEST(4030026L),

/**
* An error that indicates the App Store account wasn't found.
*
Expand Down Expand Up @@ -496,13 +559,34 @@ public enum APIError {
*/
MESSAGE_NOT_FOUND(4040015L),

/**
* An error the API returns if the service can’t find the specified test run.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/performancetestrunnotfounderror">PerformanceTestRunNotFoundError</a>
*/
PERFORMANCE_TEST_RUN_NOT_FOUND(4040018L),

/**
* An error response that indicates an app transaction doesn’t exist for the specified customer.
*
* @see <a href="https://developer.apple.com/documentation/appstoreserverapi/apptransactiondoesnotexisterror">AppTransactionDoesNotExistError</a>
*/
APP_TRANSACTION_DOES_NOT_EXIST_ERROR(4040019L),

/**
* An error that indicates a default message isn’t configured.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/defaultmessagenotfounderror">DefaultMessageNotFoundError</a>
*/
DEFAULT_MESSAGE_NOT_FOUND(4040020L),

/**
* An error that indicates that the URL for your endpoint isn’t configured.
*
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/realtimeurlnotfounderror">RealtimeUrlNotFoundError</a>
*/
REALTIME_URL_NOT_FOUND(4040021L),

/**
* An error that indicates the image identifier already exists.
*
Expand Down
103 changes: 99 additions & 4 deletions src/main/java/com/apple/itunes/storekit/client/BaseAppStoreServerAPIClient.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,26 @@
import com.apple.itunes.storekit.model.ConsumptionRequest;
import com.apple.itunes.storekit.model.ConsumptionRequestV1;
import com.apple.itunes.storekit.model.DefaultConfigurationRequest;
import com.apple.itunes.storekit.model.DefaultConfigurationResponse;
import com.apple.itunes.storekit.model.Environment;
import com.apple.itunes.storekit.model.ErrorPayload;
import com.apple.itunes.storekit.model.ExtendRenewalDateRequest;
import com.apple.itunes.storekit.model.ExtendRenewalDateResponse;
import com.apple.itunes.storekit.model.GetImageListResponse;
import com.apple.itunes.storekit.model.GetMessageListResponse;
import com.apple.itunes.storekit.model.HistoryResponse;
import com.apple.itunes.storekit.model.ImageSize;
import com.apple.itunes.storekit.model.MassExtendRenewalDateRequest;
import com.apple.itunes.storekit.model.MassExtendRenewalDateResponse;
import com.apple.itunes.storekit.model.MassExtendRenewalDateStatusResponse;
import com.apple.itunes.storekit.model.NotificationHistoryRequest;
import com.apple.itunes.storekit.model.NotificationHistoryResponse;
import com.apple.itunes.storekit.model.OrderLookupResponse;
import com.apple.itunes.storekit.model.PerformanceTestRequest;
import com.apple.itunes.storekit.model.PerformanceTestResponse;
import com.apple.itunes.storekit.model.PerformanceTestResultResponse;
import com.apple.itunes.storekit.model.RealtimeUrlRequest;
import com.apple.itunes.storekit.model.RealtimeUrlResponse;
import com.apple.itunes.storekit.model.RefundHistoryResponse;
import com.apple.itunes.storekit.model.SendTestNotificationResponse;
import com.apple.itunes.storekit.model.Status;
Expand Down Expand Up @@ -282,7 +289,7 @@ public HistoryResponse getTransactionHistory(String transactionId, String revisi
* Get a customer’s in-app purchase transaction history for your app.
*
* @param transactionId The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
* @param revision A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Note: For requests that use the revision token, include the same query parameters from the initial request. Use the revision token from the previous HistoryResponse.
* @param revision A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Note: For requests that use the revision token, include the same query parameters from the initial request. Use the revision token from the previous HistoryResponse.
* @param version The version of the Get Transaction History endpoint to use. V2 is recommended.
* @return A response that contains the customer’s transaction history for an app.
* @throws APIException If a response was returned indicating the request could not be processed
Expand Down Expand Up @@ -402,16 +409,29 @@ public void setAppAccountToken(String originalTransactionId, UpdateAppAccountTok
}

/**
* Upload an image to use for retention messaging.
* @see #uploadImage(UUID, byte[], ImageSize)
*/
@Deprecated(since = "5.1.0")
public void uploadImage(UUID imageIdentifier, byte[] image) throws APIException, IOException {
uploadImage(imageIdentifier, image, null);
}

/**
* Uploads an image to use for retention messaging.
*
* @param imageIdentifier A UUID you provide to uniquely identify the image you upload.
* @param image The image file to upload.
* @param imageSize The size of the image you upload.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/upload-image">Upload Image</a>
*/
public void uploadImage(UUID imageIdentifier, byte[] image) throws APIException, IOException {
makeHttpCall("/inApps/v1/messaging/image/" + imageIdentifier, "PUT", Map.of(), image, Void.class, PNG);
public void uploadImage(UUID imageIdentifier, byte[] image, ImageSize imageSize) throws APIException, IOException {
HashMap<String, List<String>> queryParameters = new HashMap<>();
if (imageSize != null) {
queryParameters.put("imageSize", List.of(imageSize.name()));
}
makeHttpCall("/inApps/v1/messaging/image/" + imageIdentifier, "PUT", queryParameters, image, Void.class, PNG);
}

/**
Expand Down Expand Up @@ -502,6 +522,81 @@ public void deleteDefaultMessage(String productId, String locale) throws APIExce
makeHttpCall("/inApps/v1/messaging/default/" + productId + "/" + locale, "DELETE", Map.of(), null, Void.class, null);
}

/**
* Gets the default message for a specific product in a specific locale, if it’s configured.
*
* @param productId The product identifier of the message.
* @param locale The locale of the message.
* @return The response body that contains the default configuration information.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/get-default-message">Get Default Message</a>
*/
public DefaultConfigurationResponse getDefaultMessage(String productId, String locale) throws APIException, IOException {
return makeHttpCall("/inApps/v1/messaging/default/" + productId + "/" + locale, "GET", Map.of(), null, DefaultConfigurationResponse.class, null);
}

/**
* Configures the URL for your Get Retention Message endpoint in the sandbox and production environments.
*
* @param realtimeUrlRequest The request body that includes your endpoint’s URL.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/configure-realtime-url">Configure Realtime URL</a>
*/
public void configureRealtimeURL(RealtimeUrlRequest realtimeUrlRequest) throws APIException, IOException {
makeHttpCall("/inApps/v1/messaging/realtime/url", "PUT", Map.of(), realtimeUrlRequest, Void.class, JSON);
}

/**
* Deletes the URL for your Get Retention Message endpoint, in the sandbox or production environments.
*
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/delete-realtime-url">Delete Realtime URL</a>
*/
public void deleteRealtimeURL() throws APIException, IOException {
makeHttpCall("/inApps/v1/messaging/realtime/url", "DELETE", Map.of(), null, Void.class, null);
}

/**
* Gets the URL for real-time messages that points to your Get Retention Message endpoint, which you previously configured.
*
* @return The response body that contains the URL for your Get Retention Message endpoint.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/get-realtime-url">Get Realtime URL</a>
*/
public RealtimeUrlResponse getRealtimeURL() throws APIException, IOException {
return makeHttpCall("/inApps/v1/messaging/realtime/url", "GET", Map.of(), null, RealtimeUrlResponse.class, null);
}

/**
* Initiates a performance test of your Get Retention Message endpoint in the sandbox environment.
*
* @param performanceTestRequest The request body which specifies a transaction identifier of an In-App Purchase to use for this test.
* @return The performance test response object.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/initiate-performance-test">Initiate Performance Test</a>
*/
public PerformanceTestResponse initiatePerformanceTest(PerformanceTestRequest performanceTestRequest) throws APIException, IOException {
return makeHttpCall("/inApps/v1/messaging/performanceTest", "POST", Map.of(), performanceTestRequest, PerformanceTestResponse.class, JSON);
}

/**
* Gets the results of the performance test for the specified identifier.
*
* @param requestId The ID of the performance test to return, which you receive in the PerformanceTestResponse when you call Initiate Performance Test.
* @return An object the API returns that describes the performance test results.
* @throws APIException If a response was returned indicating the request could not be processed
* @throws IOException If an exception was thrown while making the request
* @see <a href="https://developer.apple.com/documentation/retentionmessaging/get-performance-test-results">Get Performance Test Results</a>
*/
public PerformanceTestResultResponse getPerformanceTestResults(String requestId) throws APIException, IOException {
return makeHttpCall("/inApps/v1/messaging/performanceTest/result/" + requestId, "GET", Map.of(), null, PerformanceTestResultResponse.class, null);
}

/**
* Get a customer’s app transaction information for your app.
*
Expand Down
Loading
Loading