PyObjC AdServices Framework

Warnings

• breaking PyObjC dropped support for Python 3.9 with the release of v12.0 and Python 3.8 with v11.0. Ensure your Python environment meets the `requires_python` specification.
  Fix: Upgrade to Python 3.10 or later for PyObjC v12.0+.
• breaking Behavior of initializer methods (those in the 'init' family) changed in v11.1 to align with clang's documentation for Automatic Reference Counting (ARC). PyObjC now correctly models that these methods steal a reference to self and return a new reference.
  Fix: Review code interacting with Objective-C initializers, especially those involving manual reference counting or complex object graphs, to ensure correct memory management.
• gotcha PyObjC bindings do not include documentation. Users must consult Apple's official Developer Documentation for details on framework APIs (e.g., AdServices.AAAttribution classes and methods) and then apply PyObjC's bridging rules.
  Fix: Refer to Apple's documentation on `AdServices` (e.g., `AAAttribution` on developer.apple.com) and the general PyObjC documentation for bridging rules.
• gotcha In PyObjC 10.3, support for calling `__init__` when a user-defined `__new__` exists was removed, but partially reintroduced in 10.3.1. However, classes relying on PyObjC's default `__new__` still cannot use `__init__`.
  Fix: Avoid using `__init__` for PyObjC-wrapped classes that rely on PyObjC's default `__new__` implementation. If a custom `__new__` is defined, ensure `__init__` behavior is tested across PyObjC versions.
• gotcha When observing instance variables (Key-Value Observing - KVO), use `NSMutableArray` or `NSMutableDictionary` instances instead of Python lists or dicts for mutable collections. PyObjC automatically emits KVO notifications for Objective-C classes, but not for pure Python objects.
  Fix: Replace Python lists/dicts with their `Foundation` mutable counterparts (`NSMutableArray`, `NSMutableDictionary`) when these collections are observed via KVO.

Install

• pip install pyobjc-framework-adservices Install AdServices bindings

Imports

• AdServices

  import AdServices

  PyObjC maps macOS frameworks directly to Python packages with the same name.
• AAAttribution

  from AdServices import AAAttribution

  The primary class for requesting attribution tokens within the AdServices framework.

Quickstart

This example demonstrates how to request an attribution token using Apple's AdServices framework via PyObjC. It defines a completion handler to process the token or any errors, and uses `PyObjCTools.AppHelper.runEventLoop()` to manage the asynchronous callback.

import AdServices
import objc
from Foundation import NSLog
from PyObjCTools import AppHelper

def attribution_completion_handler(token, error):
    """Callback function for the attribution token request."""
    if error:
        NSLog("Error requesting AdServices attribution token: %@", error)
    else:
        NSLog("AdServices Attribution Token: %@", token)
    AppHelper.stopEventLoop() # Stop the event loop after receiving the token

def request_token():
    """Initiates the request for an AdServices attribution token."""
    NSLog("Requesting AdServices attribution token...")
    # The Objective-C method 'requestAttributionTokenWithCompletionHandler:'
    # translates to 'requestAttributionTokenWithCompletionHandler_' in PyObjC
    # (note the trailing underscore for methods that take blocks/callbacks).
    AdServices.AAAttribution.requestAttributionTokenWithCompletionHandler_(attribution_completion_handler)

if __name__ == "__main__":
    # Call the request function directly
    request_token()
    # For asynchronous operations (like network requests with callbacks),
    # a run loop is often needed to process the callback.
    # AppHelper.runEventLoop() keeps Python running until stopEventLoop() is called.
    AppHelper.runEventLoop()