AdAttributionKit Patterns

import CryptoKit
import Foundation

enum PostbackVerificationError: Error {
    case unknownKeyID
    case invalidPublicKey
    case invalidJWS
    case signatureVerificationFailed
}

struct PostbackVerifier {

    static func verify(jwsString: String) throws -> [String: Any] {
        let parts = jwsString.split(separator: ".").map(String.init)
        guard parts.count == 3 else {
            throw PostbackVerificationError.invalidJWS
        }

        let headerData = try base64URLDecode(parts[0])
        let payloadData = try base64URLDecode(parts[1])
        let signatureData = try base64URLDecode(parts[2])

        guard let header = try JSONSerialization.jsonObject(
            with: headerData
        ) as? [String: String],
              let keyID = header["kid"] else {
            throw PostbackVerificationError.invalidJWS
        }

        let publicKey = try getPublicKey(forKeyID: keyID)
        let signedData = Data("\(parts[0]).\(parts[1])".utf8)
        let signature = try P256.Signing.ECDSASignature(
            rawRepresentation: signatureData
        )

        guard publicKey.isValidSignature(signature, for: signedData) else {
            throw PostbackVerificationError.signatureVerificationFailed
        }

        guard let payload = try JSONSerialization.jsonObject(
            with: payloadData
        ) as? [String: Any] else {
            throw PostbackVerificationError.invalidJWS
        }

        return payload
    }

    static func getPublicKey(
        forKeyID keyID: String
    ) throws -> P256.Signing.PublicKey {
        let base64Key: String
        switch keyID {
        case "apple-cas-identifier/0":
            base64Key = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWdp8GPcGqmhgzEFj9Z2nSpQVddayaPe4FMzqM9wib1+aHaaIzoHoLN9zW4K8y4SPykE3YVK3sVqW6Af0lfx3gg=="
        case "apple-development-identifier/0":
            base64Key = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELeEDzpJEP+/qRSE5hJVC1p1J0ssUnQGMzBBbvnACBok8OVGGLgxL0myrKiy6lvRtSlLRsWit87i+vftD8AEqeQ=="
        case "apple-development-identifier/1":
            base64Key = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YzdO7eM97s/IJ25kdW5CZ3A14USE5IJ5Ha/vhWaxI6UBI1ZxCEvjrKxVluVGe6qWwF1BDFq+QHqKfH5u+wxHQ=="
        default:
            throw PostbackVerificationError.unknownKeyID
        }

        guard let keyData = Data(base64Encoded: base64Key) else {
            throw PostbackVerificationError.invalidPublicKey
        }
        return try P256.Signing.PublicKey(derRepresentation: keyData)
    }

    private static func base64URLDecode(_ string: String) throws -> Data {
        var base64 = string
            .replacingOccurrences(of: "-", with: "+")
            .replacingOccurrences(of: "_", with: "/")
        while base64.count % 4 != 0 {
            base64.append("=")
        }
        guard let data = Data(base64Encoded: base64) else {
            throw PostbackVerificationError.invalidJWS
        }
        return data
    }
}

{
  "jws-string": "<JWS compact serialization>",
  "conversion-value": 24,
  "ad-interaction-type": "click",
  "country-code": "US"
}

{
    "alg": "ES256",
    "kid": "example.adattributionkit"
}

{
    "impression-identifier": "7aa9f8cc-5689-4c02-b963-22ca22136015",
    "publisher-item-identifier": 525463029,
    "impression-type": "app-impression",
    "ad-network-identifier": "example.adattributionkit",
    "source-identifier": 5239,
    "timestamp": 1679790422446,
    "advertised-item-identifier": 1108187390,
    "eligible-for-re-engagement": true
}

BASE64URL(header) . BASE64URL(payload) . BASE64URL(signature)

# Private key
openssl ecparam -name prime256v1 -genkey -noout \
    -out company_adattributionkit_private_key.pem

# Public key (share with Apple during registration)
openssl ec -in company_adattributionkit_private_key.pem \
    -pubout -out company_adattributionkit_public_key.pem

import AdAttributionKit
import StoreKit

func updateConversion(value: Int, coarse: CoarseConversionValue) async {
    // Update AdAttributionKit
    do {
        try await Postback.updateConversionValue(
            value,
            coarseConversionValue: coarse,
            lockPostback: false
        )
    } catch {
        print("AdAttributionKit update failed: \(error)")
    }

    // Update SKAdNetwork
    // Note: SKAdNetwork bridges to AdAttributionKit automatically,
    // but calling both ensures coverage if only one framework has
    // active postbacks.
    do {
        try await SKAdNetwork.updatePostbackConversionValue(
            value,
            coarseValue: .high,
            lockWindow: false
        )
    } catch {
        print("SKAdNetwork update failed: \(error)")
    }
}

<!-- SKAdNetwork (legacy) -->
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>example123.skadnetwork</string>
    </dict>
</array>

<!-- AdAttributionKit -->
<key>AdNetworkIdentifiers</key>
<array>
    <string>example123.adattributionkit</string>
</array>

<key>AdAttributionKitConfigurations</key>
<dict>
    <key>AttributionWindows</key>
    <dict>
        <!-- Global settings for all ad networks -->
        <key>global</key>
        <dict>
            <key>install</key>
            <dict>
                <key>view</key>
                <integer>3</integer>  <!-- 1-7 days, default 1 -->
                <key>click</key>
                <integer>14</integer> <!-- 1-30 days, default 30 -->
            </dict>
        </dict>

        <!-- Per-network override -->
        <key>example.adattributionkit</key>
        <dict>
            <key>install</key>
            <dict>
                <key>click</key>
                <integer>7</integer>
                <key>ignoreInteractionType</key>
                <string>view</string>
            </dict>
        </dict>
    </dict>
</dict>

<key>AdAttributionKitConfigurations</key>
<dict>
    <key>AttributionCooldown</key>
    <dict>
        <!-- Hours after install before accepting new conversions -->
        <key>install-cooldown-hours</key>
        <integer>24</integer>  <!-- 0-720 hours -->

        <!-- Hours after re-engagement before accepting new conversions -->
        <key>re-engagement-cooldown-hours</key>
        <integer>12</integer>  <!-- 0-720 hours -->
    </dict>
</dict>

func handleReengagementURL(_ url: URL) {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
    if let tagItem = components?.queryItems?.first(where: {
        $0.name == Postback.reengagementOpenURLParameter
    }) {
        let conversionTag = tagItem.value
        // Persist the tag alongside an internal conversion identifier
        saveConversionTag(conversionTag)
    }
}

func updateSpecificConversion(tag: String, value: Int) async {
    let update = PostbackUpdate(
        fineConversionValue: value,
        lockPostback: false,
        conversionTag: tag,
        conversionTypes: [.reengagement]
    )
    do {
        try await Postback.updateConversionValue(update)
    } catch {
        print("Failed to update tagged conversion: \(error)")
    }
}

func safeHandleImpression(_ jwsString: String) async {
    do {
        let impression = try await AppImpression(compactJWS: jwsString)
        try await impression.handleView()
    } catch let error as AdAttributionKitError {
        switch error {
        case .invalidImpressionJWSComponents,
             .invalidImpressionJWSHeader,
             .invalidImpressionJWSPayload,
             .invalidImpressionJWSSignature:
            // Log and request a new impression from the ad network
            reportInvalidImpression(jwsString, error: error)
        case .impressionExpired:
            // Request a fresh impression
            refreshImpression()
        case .missingAttributionView:
            // Only relevant for handleTap, not handleView
            break
        default:
            print("AdAttributionKit error: \(error)")
        }
    } catch {
        print("Unexpected error: \(error)")
    }
}