# Install on iOS

> Add the NosmaiCameraSDK CocoaPod to an iOS 15 project and prepare a physical ARM64 device for camera testing.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: get-started
Source: https://nosmai.com/docs/effects/installation/ios/

## Prerequisites

- An iOS application with a deployment target of iOS 15 or later
- Xcode with command-line tools
- CocoaPods
- A physical arm64 iPhone or iPad for runtime verification
- A [Nosmai licence key](/docs/effects/license-key/) bound to the app bundle ID

## Install with CocoaPods

Add the pod to the application target:

```ruby
platform :ios, '15.0'

target 'CameraApp' do
  use_frameworks!
  pod 'NosmaiCameraSDK', '3.0.4'
end
```

Install dependencies:

```sh
pod install --repo-update
```

Open the generated `.xcworkspace`, not the `.xcodeproj`.

The `3.0.4` pod compatibility release currently resolves the verified
`nosmai.framework` archive from the iOS `v3.0.4` GitHub release. The archive is
SHA-256 pinned by the podspec.

## Add permission descriptions

Add only the descriptions required by enabled application flows:

```xml
<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone when recording video.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app saves captured photos and videos to your library.</string>
```

`NSCameraUsageDescription` is required for preview. Microphone access is needed
only when recording audio. Photo Library Add access is needed only when the host
app saves output to Photos.

## Configure the target

Confirm these settings:

- iOS deployment target is `15.0` or later
- the application target is selected, not a test or extension target
- a physical iOS device or `Any iOS Device (arm64)` is selected
- application signing uses the bundle identifier registered in Nosmai Console
- the final app contains `Frameworks/nosmai.framework`

The CocoaPod excludes iOS Simulator architectures because the proprietary
framework is device-only. Do not work around that exclusion by copying an
unverified framework into the Pods directory.

## Manual framework installation

Use manual installation only when the project cannot use CocoaPods.

1. Download `nosmai.framework.zip` and `SHA256SUMS` from the
   [official iOS release](https://github.com/nosmai/nosmai_effects_sdk_ios/releases/tag/v3.0.4).
2. Verify the archive:

```sh
shasum -a 256 -c SHA256SUMS
```

The expected framework ZIP SHA-256 is:

```text
f63f566f2580c25360d29e667308a127360e558198f05ad437ff1dd5e7a01157
```

3. Unzip the archive.
4. Add `nosmai.framework` to the application target.
5. Set it to **Embed & Sign**.
6. Link the Apple frameworks listed by the release podspec.

Do not install CocoaPods and a manual copy at the same time. Two embedded copies
can cause duplicate symbols or runtime loading ambiguity.

## Framework size

The verified iOS release ZIP is 23,962,678 bytes, about 22.9 MiB compressed.
This is not the final App Store download increase. App thinning, compression,
symbols, existing linked frameworks, and bundled `.nosmai` assets change the
signed application result.

Measure an Archive build for the device family that will ship.

## Verify it worked

Add a compile-only import to an Objective-C source file:

```objc
#import <nosmai/Nosmai.h>

NSString *version = [NosmaiCore shared].version;
NSLog(@"Nosmai version: %@", version);
```

Build the application for a physical device. A successful build and launch with
the version log confirms the framework is linked. Continue to the
[iOS quickstart](/docs/effects/quickstart/ios/) to initialize the licence,
request the camera, and apply a visible effect.

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| `No such module 'nosmai'` | The workspace or pod target is not being used | Run `pod install` and open the `.xcworkspace` |
| `'nosmai/Nosmai.h' file not found` | The framework is missing from the application target | Reinstall the pod or add the verified framework to the correct target |
| `building for iOS Simulator, but linking in object file built for iOS` | A simulator target was selected | Build and run on a physical arm64 iOS device |
| `dyld: Library not loaded: @rpath/nosmai.framework/nosmai` | Manual framework was linked but not embedded | Set `nosmai.framework` to **Embed & Sign** |
| App closes when asking for camera access | `NSCameraUsageDescription` is missing | Add the camera usage string before requesting permission |

## Next steps

- [Add real-time camera effects to an iOS app](/docs/effects/quickstart/ios/)
- [Get and apply a licence key](/docs/effects/license-key/)
- [Check iOS capability support](/docs/effects/platform-support/)
- [Apply a beauty filter on iOS](/docs/effects/guides/effects/apply-a-beauty-filter/ios/)
- [Control a camera game on iOS](/docs/effects/guides/effects/control-a-camera-game/ios/)

## References

- [Nosmai iOS releases](https://github.com/nosmai/nosmai_effects_sdk_ios/releases/latest)
- [Nosmai Effects](https://nosmai.com/effects/)
- [Nosmai Effects pricing](https://nosmai.com/effects/#pricing)