Manage showcase API processes

Create Showcase & Creative ("Happy" Path)

Description

Organization that is a location owner or delegated partner creates a showcase, targeting a single location, and a showcase creative. The location owner has its own app and adds a call-to-action that's expected to invoke their app in Apple Maps.

Preconditions

• Organization's brand is approved
• API user has successfully created a location which includes action link details (quicklinks)
• Targeted location's resource state is PUBLISHED, or the location has a version that was previously PUBLISHED. If the location has never been PUBLISHED, wait until it is before you create the showcase. Otherwise, the showcase will fail to publish.

note

Refer to Create Resource sequence diagram for information on how to create a location

Add Image

1. API user requests image upload
2. Service validates request
3. If no exceptions, then 202 Accepted is returned
4. Response body includes image id

Get (Image) Metadata

1. Using the imageId returned in a previous steps, the API user requests^* image metadata to check resource state
2. Service validates request
3. If no exceptions, then 200 OK is returned
4. If response body's resource state is APPROVED, then API user may proceed. Else, API user periodically calls the service until APPROVED is indicated before proceeding

Get Call-to-Action

1. API user requests a list of available call-to-action types which exist at the time of request
2. Service validates request
3. If no exceptions, then 200 OK is returned
4. Response body include a list of available call-to-action types

Create Showcase Creative

1. API user requests creation of showcase creative

• photo id is set using the image id returned by the Get Metadata service
• callToAction is set using a single type returned by the Get CTAs service Optionally, passing in appIds
• All other mandatory fields are set

2. Service validates request
3. System synchronously validates partner data
4. If no exceptions, then 201 Created is returned
5. System asynchronously validates partner data
6. If no exceptions, then Feedback is not generated
7. Showcase creative moves to IN_REVIEW state
8. Service "listens" for event indicating resource is APPROVED
9. Service captures Feedback and generates Notification when event message is received
10. Periodically API user requests Notifications
11. Notification indicates that resource is APPROVED

tip

Poll for notifications every 15 minutes

Get Location

1. Using the id of the targeted location, the API user requests the location to check its resource state
2. Service validates request
3. If no exceptions, then 200 OK is returned
4. If response body's resource state is PUBLISHED, or the location has previously been PUBLISHED, then API user may proceed. Else, API user periodically calls the service until PUBLISHED is indicated before proceeding

Create Showcase

1. API user requests creation of showcase

• creativeId is set using the id of the Showcase Creative in a previous steps
• resourceId is set using the id of the targeted Location

2. Service validates request
3. System synchronously validates partner data
4. If no exceptions, then 201 Created is returned
5. System asynchronously validates partner data
6. If no exceptions, then Feedback is not generated
7. Showcase moves to IN_REVIEW state
8. Service "listens" for event indicating resource is APPROVED
9. Service captures Feedback and generates Notification when event message is received
10. Periodically API user requests Notifications
11. Notification indicates that resource is APPROVED

tip

Poll for notifications every 15 minutes

note

If the targeted location has never been PUBLISHED when the Showcase publication process is initiated, the Showcase moves to REJECTED and is not resubmitted when the location is later published. After the location is PUBLISHED, update the Showcase to resubmit it. Refer to Resource ID for details.