# Phone

The Phone module collects a user's phone number and can confirm phone ownership by sending a one-time password (OTP) via SMS.

For an overview of this module and how it works, see [Phone Number Input](https://developer.incode.com/docs/phone-number-input).

How you use this module depends on your integration pattern. When the app defines the steps in code, you add the module to an `IncdOnboardingFlowConfiguration` as shown below; when the flow is defined in Dashboard, you reference it by ID. See [Integration Approaches](https://developer.incode.com/docs/ios-flow-configuration).

**Availability:** All variants; the `-sna` build adds [Silent Network Authentication](https://developer.incode.com/docs/glossary#sna) features.

**UI:** v1 and v2.

## Add Phone

Add the module with `addPhone()`. Both parameters are optional; call `addPhone()` with no arguments to use the default configuration.

```swift
flowConfig.addPhone(
    otpVerification: true,
    defaultRegionPrefix: 1     // optional dial code, 1…9999
)
```

### Example

The example below builds a flow with the Phone module, enables OTP verification, starts onboarding, and listens for the result through `onAddPhoneNumberCompleted(_:)` on `IncdOnboardingDelegate`.

```swift
final class VerificationCoordinator: IncdOnboardingDelegate {

    func startVerification(sessionToken: String) {
        let flow = IncdOnboardingFlowConfiguration()
        flow.addPhone(otpVerification: true)

        let session = IncdOnboardingSessionConfiguration(token: sessionToken)
        IncdOnboardingManager.shared.startOnboarding(
            sessionConfig: session,
            flowConfig: flow,
            delegate: self
        )
    }

    // MARK: - IncdOnboardingDelegate

    func onAddPhoneNumberCompleted(_ result: PhoneNumberResult) {
        // Phone number captured. Process the result.
        let phone = result.phone
    }
}
```

## Configuration Options

Configure the module with `addPhone()`.

| Option                | Type    | Description                                                                                                                                                                                                                                                         |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `otpVerification`     | `Bool?` | If `true`, shows OTP verification after the user enters a phone number. When `nil`, shows the value configured on the Workflow (via `OTPConfiguration`) or the manager flag.                                                                                        |
| `defaultRegionPrefix` | `Int?`  | Sets a dialing prefix that overrides the prefix derived from the carrier or the device's current region. Valid values are integers greater than `0`, up to four digits; invalid values are ignored and the default region prefix is used. Do not add a leading `+`. |

You can also enable SMS OTP globally on the manager with `enableSMSOTPVerification`: a `UserDefaults`-backed flag, `false` by default. OTP expiration and prefill are determined by the Workflow's `OTPConfiguration`.

## Enable Silent Network Authentication

[Silent Network Authentication](https://developer.incode.com/docs/silent-network-authentication-sna) (SNA) is a phone number verification method that authenticates users through their mobile network using real-time carrier signals. You can enable SNA for the Phone module. SNA is only available in Flows in Dashboard, not Workflows.

1. Use an iOS SDK variant that includes the `-sna` suffix: for example, `5.43.0-s-sna`.
2. In a Flow in Dashboard, turn on **_Enable SNA verification_** in the [Phone Number Input](https://developer.incode.com/docs/phone-number-input-dashboard) module.
3. Start the onboarding flow using one of the following approaches:
   - `startFlow` **or** `startOnboarding`: Specify `configurationId` inside `IncdOnboardingSessionConfiguration`, and provide it as `sessionConfig` to `startFlow` or `startOnboarding` method.
   - **Sections**: Specify `configurationId` inside `IncdOnboardingSessionConfiguration`, and provide it as `sessionConfig` to `setupOnboardingSession`. Then call `startOnboardingSection` with the Phone module provided to `IncdOnboardingSessionConfiguration`.

## Result

Phone delivers a `PhoneNumberResult` to the `onAddPhoneNumberCompleted(_:)` callback on your `IncdOnboardingDelegate`:

```swift
func onAddPhoneNumberCompleted(_ result: PhoneNumberResult)
```

`PhoneNumberResult` fields:

- `phone: String?`: The phone number captured from the user; `nil` when unavailable.
- `error: IncdError?`: The error that occurred while capturing the phone number, if any; otherwise, `nil`.

<br />