Available from v2.13.0
BackbaseCountryCore
BackbaseCountryCore is the foundational module for handling country-related data in iOS applications. It includes protocols, implementations, and data for country names and phone codes for 249 countries worldwide using ISO 3166-1 alpha-2 country codes.
It includes the following features:
- Localised country names using device locale.
- International phone codes for all countries.
- Extensible protocol-based architecture.
- Bundle-level data customisation support.
- Runtime override capabilities.
API reference
CountryCoreFactory
The CountryCoreFactory class serves as the main entry point for creating and configuring country provider instances in the Country Core framework. It behaves like a container which initialises and provides access to the default implementations of country name and phone code providers. If you do not specify a custom list via the countries parameter, the factory loads the full list from the bundled country-codes.json file.
This class supplies the default implementations for country names and phone codes through its built-in providers. For detailed information about each provider's functionality, see the Data Providers section.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
nameProvider |
CountryProvider |
Localised country names |
|
phoneCodeProvider |
CountryProvider |
International phone codes |
|
iconsProvider |
CountryFlagProvider? |
Optional flag provider; requires BackbaseCountryIcons |
|
worldCountries |
[String] |
Array of 249 ISO 3166-1 alpha-2 country codes |
Initialiser
public init(iconsProvider: CountryFlagProvider? = nil, countries: [String]? = nil)
Parameters
|
Property |
Type |
Description |
|---|---|---|
|
iconsProvider |
CountryFlagProvider? |
Optional. Pass a flag provider from BackbaseCountryIcons to include flag images, or omit for core features only. |
|
countries |
[String]? |
Custom country list. If nil uses all 249 countries. |
Core protocols
CountryProvider protocol
A generic protocol for providing country-related string data.
Methods
- getValue(of:)
- Returns: String, the name of the country or phone code from the country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
- setValue(_:of:)
- Used to override the value for a specific country during the run time.
|
Parameter |
Type |
Description |
|---|---|---|
|
value |
String |
The string value to set |
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Properties
|
Parameter |
Type |
Description |
|---|---|---|
|
exceptions |
[String: String] |
Used for error handling scenarios for a specific country/phone codes |
The exceptions property includes custom overrides that have been set using the setValue method. Always check the exceptions property for these overrides before calling getValue to ensure you are accessing the correct value.
CountryFlagProvider protocol
A specialised protocol for country flag images which is implemented by BackbaseCountryIcons.
Methods
- getValue(of:)
- Returns: UIImage? the flag image from the country code
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
- setValue(_:of:)
- Used to override the image for a specific country during the run time.
|
Parameter |
Type |
Description |
|---|---|---|
|
value |
UIImage |
The UIImage to use as the flag |
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Properties
|
Parameter |
Type |
Description |
|---|---|---|
|
exceptions |
[String: UIImage] |
Used for error handling scenarios for a specific country codes |
Data providers
CountryNameProvider
Provides localised country names
- Data Source: iOS system locale, NSLocale.current by using country codes from bundled JSON file, country-codes.json
- Localisation: Automatically adapts to device language settings
- Fallback: System-provided country names
- Customisation: Runtime overrides via setValue
Country names are localised based on the user's device settings. Test with different locales to ensure proper display for your target markets.
CountryPhoneCodeProvider
Provides international phone codes
- Data Source: Bundled JSON file, phone-codes.json
- Coverage: 249 countries with their respective phone codes
- Format: International format with '+' prefix, for example, "+1", "+44"
- Customisation: Runtime overrides and bundle-level JSON replacement
Phone codes are loaded from JSON at initialisation. For better performance in list views, consider caching the codes you need frequently.
Data sources
BackbaseCountryCore uses bundled JSON files as data sources for country codes and phone codes. You can customise the data by providing your own country-codes.json and phone-codes.json files in your main app bundle. For examples, see Bundle-level customisation section.
Country codes (country-codes.json)
An array of 249 ISO 3166-1 alpha-2 country codes:
[
"US", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR",
// ... 239 more countries
]
Phone Codes (phone-codes.json)
A dictionary mapping country codes to international phone codes:
{
"AD": "+376",
"AE": "+971",
"AF": "+93",
"AG": "+1-268",
// ... 245 more mappings
}
Error handling
The following error cases are available:
public enum CountryCoreError: Error, Equatable {
case phoneCodeMissing(forCountryCode: String)
case nameMissing(forCountryCode: String)
case flagMissing(forCountryCode: String) // Used by BackbaseCountryIcons
}
Catch specific error cases to access the associated country code values. This enables meaningful error messages and appropriate fallback behavior.
Usage
Basic setup - core only
import BackbaseCountryCore
// Create factory without flag provider
let countryCore = CountryCoreFactory()
// Access country data
let countries = countryCore.worldCountries // 249 countries
let nameProvider = countryCore.nameProvider
let phoneProvider = countryCore.phoneCodeProvider
Getting country information
// Get localised country name
do {
let countryName = try countryCore.nameProvider.getValue(of: "US")
print(countryName) // "United States" (or localised equivalent)
} catch CountryCoreError.nameMissing(let code) {
print("Country name not found for: \(code)")
} catch {
print("Unexpected error: \(error)")
}
// Get international phone code
do {
let phoneCode = try countryCore.phoneCodeProvider.getValue(of: "US")
print(phoneCode) // "+1"
} catch CountryCoreError.phoneCodeMissing(let code) {
print("Phone code not found for: \(code)")
} catch {
print("Unexpected error: \(error)")
}
Custom country lists
// Create factory with specific countries only
let europeanCountries = ["DE", "FR", "IT", "ES", "NL", "BE", "AT", "CH"]
let euroCore = CountryCoreFactory(countries: europeanCountries)
print("European countries: \(euroCore.worldCountries.count)") // 8
Runtime overrides
// Override country name
countryCore.nameProvider.setValue("Custom Country Name", of: "US")
// Override phone code for a new region
countryCore.phoneCodeProvider.setValue("+999", of: "XX")
// Check if override exists
if countryCore.nameProvider.exceptions["US"] != nil {
print("US has a custom name override")
}
Batch processing
// Process all countries efficiently
func processAllCountries() {
let countries = countryCore.worldCountries
for countryCode in countries {
do {
let name = try countryCore.nameProvider.getValue(of: countryCode)
let phoneCode = try countryCore.phoneCodeProvider.getValue(of: countryCode)
// Process country data
print("\(countryCode): \(name) (\(phoneCode))")
} catch {
print("Error processing \(countryCode): \(error)")
}
}
}
Bundle-level customisation
Override data files
Place the following files in your main app bundle to customize default data.
YourApp.app/
├── country-codes.json // Custom list of supported countries
└── phone-codes.json // Custom phone code mappings
Example custom country-codes.json:
[
"US", "CA", "GB", "DE", "FR", "JP", "AU"
]
Example custom phone-codes.json:
{
"US": "+1",
"CA": "+1",
"GB": "+44",
"DE": "+49",
"FR": "+33",
"JP": "+81",
"AU": "+61"
}
Integration with BackbaseCountryIcons
BackbaseCountryCore works independently but integrates with BackbaseCountryIcons to provide flag images. BackbaseCountryIcons depends on BackbaseCountryCore and implements the CountryFlagProvider protocol defined in Core. For more information on the flag-specific features, see the BackbaseCountryIcons documentation.
import BackbaseCountryCore
import BackbaseCountryIcons
// Complete setup with flag provider
let countryCore = CountryCoreFactory(
iconsProvider: BackbaseCountryIcons.countryFlagProvider
)
// Now you have access to all country data including flags
let name = try? countryCore.nameProvider.getValue(of: "US")
let phoneCode = try? countryCore.phoneCodeProvider.getValue(of: "US")
let flag = try? countryCore.iconsProvider?.getValue(of: "US")
Design tokens
The BackbaseCountryCore framework includes data-only classes and does not use design tokens directly. UI components that consume BackbaseCountryCore can apply appropriate design tokens to manage visual presentation. For more information, see CountrySelector and PhoneInput components.
Dependencies
- Foundation: Core iOS framework.
- External dependencies: None. Works independently.
See also
- BackbaseCountryIcons - Flag images and provider implementation
- CountrySelector - UI component for country selection
- PhoneInput - Phone number input with country selection