ContactProviderManager Fails with Custom domainIdentifier, Works Only with "defaultDomain"

Has anyone encountered a situation like mine below? I’ve submitted feedback, but it seems like I’ll have to wait for a while.

ContactProviderManager Fails with Custom domainIdentifier, Works Only with "defaultDomain"

Category: Developer Tools / Frameworks Subcategory: ContactProvider Framework Reproducibility: Always iOS Version: iOS 18.0 (and later) Xcode Version: Xcode 16.0 (or later) 

Description: When initializing a ContactProviderManager with a custom ContactProviderDomain using any identifier other than "defaultDomain", the initializer throws a ContactProviderError.domainNotRegistered error. The documentation for ContactProviderDomain (https://developer.apple.com/documentation/contactprovider/contactproviderdomain) does not provide any method to register custom identifiers, making it impossible to use ContactProviderManager with a desired custom identifier. The only successful case is when the identifier is "defaultDomain". print("Error: (error)") // No error, initialization succeeds

Steps to Reproduce:

  1. Create a Contact Provider Extension in an iOS app targeting iOS 18.0.

  2. In host app, Attempt to initialize a ContactProviderManager with a custom ContactProviderDomain identifier:


​import ContactProvider
func enableExtensionExample() async {
    do {
        // The app creates a contact provider manager with custom domain.
        let manager =  try ContactProviderManager(domainIdentifier: "com.mycompany.customdomain")
        
        // May prompt the person to enable the custom domain.
        try await manager.enable()
    } catch {
       print("Error: \(error)") // Prints ContactProviderError.domainNotRegistered
    }
}

  1. Try the same with the default identifier:

​import ContactProvider
func enableExtensionExample() async {
    do {
        // The app creates a contact provider manager with a default domain.
        let manager =  try ContactProviderManager(domainIdentifier: "defaultDomain")
        
        // May prompt the person to enable the default domain.
        try await manager.enable()
    } catch {
       print("Error: \(error)") // No error, initialization succeeds
    }
}

  1. Build and run the app on a device or simulator running iOS 18.0 or later.

  2. Observe that the initializer fails with domainNotRegistered for any identifier other than "defaultDomain".

Expected Behavior:

The ContactProviderManager should initialize successfully with any valid ContactProviderDomain identifier, provided the domain is properly configured or registered, allowing developers to use custom identifiers for organizing contacts (e.g., for different categories or sources).

Actual Behavior:

The ContactProviderManager initializer throws ContactProviderError.domainNotRegistered for any ContactProviderDomain identifier other than "defaultDomain". Only the "defaultDomain" identifier succeeds, limiting the ability to use custom domains.

Impact:

Developers cannot use custom identifiers to categorize or manage contacts in separate domains, restricting the ContactProvider framework’s flexibility. This forces reliance on the "defaultDomain" identifier, which may not suit use cases requiring distinct contact groups (e.g., personal vs. business contacts).

Suggested Fix:

Provide an API to register custom ContactProviderDomain identifiers, such as a ContactProviderManager.register(domain:) method. Update the ContactProviderDomain and ContactProviderManager documentation to clarify how to use custom identifiers or explicitly state if only "defaultDomain" is supported. If custom identifiers are not intended to be supported, document this limitation clearly to avoid developer confusion.

Feedback : FB20104001 (ContactProviderManager Fails with Custom domainIdentifier, Works Only with "defaultDomain")

Thank you for filing your Feedback report. Your issue is a known limitation. Registering custom domains is unsupported.

Thank you for your response to my previous feedback , confirming that registering custom ContactProviderDomain identifiers is a known limitation and currently unsupported. I am submitting this follow-up to seek clarification on this limitation and request improvements to the documentation to prevent confusion for other developers.

Background:

The ContactProvider framework allows creating a ContactProviderDomain with a custom identifier, but initializing ContactProviderManager with any identifier other than "defaultDomain" results in a ContactProviderError.domainNotRegistered error. Your response clarified that custom domains are unsupported, but the documentation does not explicitly state this limitation, leading to confusion.

Questions for Clarification

Future Support:
Is there a plan to support registering custom ContactProviderDomain identifiers in future iOS versions (e.g., iOS 18.2, iOS 19.0)? If so, can you provide an estimated timeline?
If custom domains will remain unsupported, can this be confirmed as a permanent design decision?

Documentation Improvement:
Can the documentation for ContactProviderDomain and ContactProviderManager be updated to explicitly state that only the "defaultDomain" identifier is supported, to avoid misleading developers?
Can additional guidance be added to explain why custom domains are unsupported or suggest alternative approaches for managing multiple contact groups?

Alternative Approaches:
For apps needing to categorize contacts (e.g., personal vs. business), what is the recommended approach within the ContactProvider framework, given the lack of custom domain support? For example, should developers rely on ContactItem.Identifier prefixes?
Are there plans to introduce new APIs (e.g., register(domain:)) to support custom domains or other contact organization methods?

Error Clarity:

Can the documentation for ContactProviderError.domainNotRegistered clarify that this error occurs due to the lack of custom domain support, rather than a configuration issue?

Impact:

The lack of clear documentation and the unsupported custom domain feature cause confusion and wasted development time. Developers may assume custom identifiers are functional due to the ContactProviderDomain API, only to encounter errors. Clarifying this limitation and providing alternative solutions would greatly improve the developer experience.Suggested Actions: Update the documentation to explicitly state that only "defaultDomain" is supported for ContactProviderDomain.
Provide guidance on alternative methods for categorizing contacts.
If custom domains will be supported in the future, include a note about planned enhancements.

Please file your suggestion using Feedback Assistant, then post the number here.

ContactProviderManager Fails with Custom domainIdentifier, Works Only with "defaultDomain"
 
 
Q