A structure that represents an attributable impression the developer generates in response to a
person's interaction with an ad in an app.
To record a view-through impression, call ``beginView()`` when the ad content corresponding to the
impression becomes visible, and ``endView()`` when the ad content disappears. The advertisement
needs to be visible for at least two seconds for AdAttributionKit to record a view through impression;
otherwise, the framework throws an error.
> Important: Regenerate an `AppImpression` for each ad you show. Don’t reuse `AppImpression` structures across multiple ads.
To support click-through attribution, place a
<doc://com.apple.documentation/documentation/UIKit/UIEventAttributionView>
over the ad content and call either ``AppImpression/handleTap(reengagementURL:)`` or
``AppImpression/handleTap()`` after a person taps the ad content.
The framework then validates that a person taps a `UIEventAttributionView`
before recording the impression, and throws an error if it can't validate that a tap occurred in a
`UIEventAttributionView`.
After the framework validates the tap, it records the impression and then attempts to
launch one of the user's installed marketplaces to show the product page for the advertised app.
The system uses the advertised item ID from the JSON Web Signature (JWS) string you provide to initialize
the `AppImpression`, in addition to the user's preferred marketplaces, to help determine which marketplace
the framework needs to launch. If the app is already installed, the framework launches into the app's Home Screen instead.
In iOS 18 and later, `AppImpression` supports reengagement for click-through interactions when the advertised app is already
installed on the device. The system can deep-link into the advertised app when using
``AppImpression/handleTap(reengagementURL:)``. Click-through impressions can also qualify for reengagement
postbacks by opting in for reengagement in the impression JWS. For more information about opting in for re-engagement,
see <doc:generating-jws-impressions>.
## Displaying view-through ads.
- ``beginView()``
- ``endView()``
## Processing interactions with click-through ads.
- ``handleTap()``
- ``handleTap(reengagementURL:)``
## Instance methods
- ``hash(into:)``
Creates a new app impression with the provided compact JSON Web Signature (JWS).
Create a new `AppImpression` by providing a compact string representation of the JWS as
the following example shows:
- Parameters:
- compactJWS: A string that represents a JWS.
```swift
do {
let impression = try await AppImpression(compactJWS: compactJWS)
print("Impression advertised item ID: \(impression.advertisedItemID)")
}
catch {
print("Failed to decode impression: \(error)")
}
```
method · iOS 26.2+
handleView
TypeScript
handleView(): Promise<void>
Swift declaration
func handleView() async throws
Records a view-through impression with simplified single-call processing.
Use this method to record a view-through impression when you have determined that the ad
was meaningfully viewed by the user. Unlike ``beginView()`` and ``endView()``, this method
trusts your application to handle view duration and visibility validation.
```swift
func handleAdViewed(impression: AppImpression) async {
do {
try await impression.handleView()
}
catch {
print("Failed to record view-through impression: \(error).")
}
}
```
> Important: This method is only available in iOS 26.2 and later. For earlier versions,
use ``beginView()`` and ``endView()``.
get · iOS 17.4+
adNetworkID
TypeScript
get adNetworkID(): string
Swift declaration
var adNetworkID: String { get }
The advertising network ID.
get · iOS 18.0+
isSupported
TypeScript
static get isSupported(): boolean
Swift declaration
static var isSupported: Bool { get }
A Boolean value that indicates whether the framework supports app impressions on a person's device.
Check this value to ensure the current device supports app impressions before calling methods on an `AppImpression`.
- Returns: `true` if the current device supports app impressions; otherwise, `false`.
get · iOS 17.4+
publisherItemID
TypeScript
get publisherItemID(): number
Swift declaration
var publisherItemID: UInt64 { get }
The publisher app's item ID.
get · iOS 17.4+
advertisedItemID
TypeScript
get advertisedItemID(): number
Swift declaration
var advertisedItemID: UInt64 { get }
The advertised item's ID.
get · iOS 18.0+
eligibleForReengagement
TypeScript
get eligibleForReengagement(): boolean
Swift declaration
var eligibleForReengagement: Bool { get }
A Boolean value that indicates whether this impression is eligible for reengagement.
get · iOS 17.4+
compactJWSRepresentation
TypeScript
get compactJWSRepresentation(): string
Swift declaration
var compactJWSRepresentation: String { get }
A string that presents the compact representation of the impression's JSON Web Signature (JWS).
get · iOS 17.4+
id
TypeScript
get id(): string
Swift declaration
var id: UUID { get }
The impression's unique ID.
get · iOS 17.4+
keyID
TypeScript
get keyID(): string
Swift declaration
var keyID: String { get }
The JSON Web Signature (JWS) key ID.
method · iOS 17.4+
endView
TypeScript
endView(): Promise<void>
Swift declaration
func endView() async throws
Ends the view-through impression when the ad content corresponding to the impression disappears.
End the view-through impression, as the following example shows:
```swift
func handleAdDisappeared(impression: AppImpression) async {
do {
try await impression.endView()
}
catch {
print("Failed to end view-through impression: \(error).")
}
}
```
get · iOS 17.4+
sourceID
TypeScript
get sourceID(): number
Swift declaration
var sourceID: Int { get }
A four-digit integer that ad networks define to represent the ad campaign.
The `sourceID` is also known as the _hierarchical source identifier_. Ad networks and developers define its meaning.
This integer can have up to four digits. You might receive two, three, or all four digits of the `sourceID` in the first winning
postback, based on the data tier of the postback. You can use the different digits of the source identifier to represent different
aspects of your ad, such as campaign information, placement, locale, and so on. For more information about the
values you might get in the postback, see <doc:identifying-the-parameters-in-a-postback>.
> Note: A postback report represents this integer as a string in the `source-identifier` parameter in the payload of the
JSON Web Signature (JWS). For more details about the parameters of a postback, see
<doc:identifying-the-parameters-in-a-postback>.
method · iOS 17.4+
beginView
TypeScript
beginView(): Promise<void>
Swift declaration
func beginView() async throws
Begins recording a view-through impression when ad content corresponding to the impression becomes visible.
Begin the view impression process by calling ``AppImpression/beginView()``, as the following example shows:
```swift
func handleAdAppeared(impression: AppImpression) async {
do {
try await impression.beginView()
}
catch {
print("Failed to begin view-through impression: \(error).")
}
}
```
Processes click-through interactions on your custom rendered ad content, and delivers a URL to the advertised app if it's
installed.
- Parameters:
- reengagementURL: A universal link into the advertised app that the framework attempts to open.
Use this method to provide a URL to deeply link someone into an advertised app if they have the app installed.
If the system can validate that a person tapped the custom rendered ad content, it attempts to either launch one of
the installed marketplaces to show the product page to install the advertised app, or performs a reengagement if the
advertised app is already installed, and opens the reengagement URL.
AdAttributionKit requires the URL to be a universal link specifically for the advertised app that the framework uses at runtime
to attempt to open the app. If the URL isn't a universal link, or the universal link isn't registered to the advertised app, the
framework disregards the URL and
launches the app as usual without passing the URL. For more information, see
<doc://com.apple.documentation/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/>
and <doc://com.apple.documentation/documentation/xcode/supporting-universal-links-in-your-app>.
method · iOS 17.4+
handleTap
TypeScript
handleTap(): Promise<void>
Swift declaration
func handleTap() async throws
Processes click-through interactions on your custom rendered ad content.
Handle a person tapping your ad content by calling the app impression's handle tap method.
If the system can validate that person tapped, it attempts to either launch one of the installed marketplaces
to show the product page to install the advertised app, or it performs a reengagement if someone already has the advertised
app installed, and opens it directly.
This API requires that you place a <doc://com.apple.documentation/documentation/UIKit/UIEventAttributionView>
on top of your ad content before calling `handleTap()`, as the following example shows:
```swift
func handleAdTapped(impression: AppImpression) async {
do {
// This fails if a person didn't tap a `UIEventAttributionView`.
try await impression.handleTap()
}
catch {
print("Failed to perform click-through impression: \(error).")
}
}
```
> Note: This method is only available for 15 minutes after you create the `impression`. After 15 minutes, you need to initialize a
new `AppImpression` instance if you want to use the click-through ad API. This limitation doesn’t apply to
view-through ads. For more information on view-through and click-through ads,
see <doc:presenting-ads-in-your-app>.
get · iOS 17.4+
timestamp
TypeScript
get timestamp(): globalThis.Date
Swift declaration
var timestamp: Date { get }
The impression's timestamp, in milliseconds since 1970.
