## Add the Merchant Library  
### Include Dependency  
To get started, add the Button Merchant Library through [CocoaPods](https://cocoapods.org/), [Carthage](https://github.com/Carthage/Carthage) or Swift Package Manager.

#### Swift Package Manager
```javascript
In Xcode, navigate to **File → Swift Packages → Add Package Dependency**

https://github.com/button/button-merchant-ios
```

```ruby
pod 'ButtonMerchant', '~> 1.5'
```

```swift
dependencies: [
    .package(url: "https://github.com/button/button-merchant-ios", .upToNextMajor(from: "1.5.0"))
]
```

```shell
github "button/button-merchant-ios" ~> 1.5
```

### Allow auto-updating  
The Button Merchant Library is strictly semantically versioned so we strongly recommend allowing automatic updates up to the next major version.

Before continuing run `pod install`, `carthage build` or allow Swift Package Manager to include the Button Merchant Library, depending on your method of inclusion.

### Setup Library  
In your AppDelegate file, import `ButtonMerchant` and initialize it by calling the `ButtonMerchant.configure` method passing your iOS Application ID registered in the Button Dashboard.

Additionally, some users will be initializing your application from a fresh install after following a promotion. In order to fulfill these specific user requests, include a call to the `ButtonMerchant.handlePostInstallURL` method. This will fetch the user’s destination url prior to the fresh install, and allow you to route them directly to your relevant promotion. The `handlePostInstallURL` method will pass a non-nil url to the callback only once, upon first app launch following an install from a [Button Link](https://developer.usebutton.com/docs/web-app-links).

#### Swift
```swift
import ButtonMerchant

func application(_ application: UIApplication, didFinishLaunchingWithOptions
                 launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  // Replace app-xxxxxxxxxxxxxxxx with your App ID from the
  // Button Dashboard https://app.usebutton.com
  ButtonMerchant.configure(applicationId: "<#app-xxxxxxxxxxxxxxxx#>")

ButtonMerchant.handlePostInstallURL { url, error in

guard let url = url else {
			// If nil is returned, you can exit the callback
    		// and route the user as normal
		}
		// Parse the returned URL and redirect
		// the user to the correct destination in your app
	}

return true
}
```

#### Objective-C
```objectivec
@import ButtonMerchant;

- (BOOL)application:(UIApplication *)application
   didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

// Replace app-xxxxxxxxxxxxxxxx with your App ID from the Button Dashboard https://app.usebutton.com
    [ButtonMerchant configureWithApplicationId:@"<#app-xxxxxxxxxxxxxxxx#>"];

[ButtonMerchant handlePostInstallURL:^(NSURL * _Nullable url, NSError * _Nullable error) {
      if (url) {
        // Route user to the url
      }
    }];

return YES;
  }
```

## Register Deep Links  
Button’s Merchant Library will abstract any complexities of token management for you, including extracting the token from any incoming deeplinks.

For users that have already installed your application and are entering from another application’s promotion, Button’s Merchant library will help you source where they came from. Pass the incoming URL to the Button Merchant Library in order to accurately attribute and handle their intent.

The `ButtonMerchant` class allows you to handle both [Universal Links](https://developer.apple.com/ios/universal-links/) by passing incoming user activity to `trackIncomingUserActivity`, and Custom Scheme URLs by passing incoming URLs to `trackIncomingURL`.

It is important that `trackIncomingURL` and `trackIncomingUserActivity` are called immediately. If the link that opens the app is not a Button Link, the Merchant Library will make this determination and Button will not be a part of the user journey.

#### Swift (AppDelegate)
```swift
// Handle custom scheme urls
func application(_ app: UIApplication, open url: URL,
                 options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {

ButtonMerchant.trackIncomingURL(url)

// Your normal deep link route handling to show the user the content

return true
}

// Handle Universal Links
func application(_ application: UIApplication, continue
                 userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool {

ButtonMerchant.trackIncomingUserActivity(userActivity)

// Your normal deep link route handling to show the user the content

return true
}
```

#### Swift (Scene Delegate)
```swift
// Handle when the app is launched by a deeplink:
func scene(_ scene: UIScene, willConnectTo
           session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {

// Handle custom scheme urls
  if let url = connectionOptions.urlContexts.first?.url {
    ButtonMerchant.trackIncomingURL(url)
  }

// Handle Universal Links
  if let url = connectionOptions.userActivities.first?.webpageURL {
    ButtonMerchant.trackIncomingUserActivity(userActivity)
  }
}

// Handle incoming deeplinks when the app is already running:

// Handle custom scheme urls
func scene(_ scene: UIScene, openURLContexts
           URLContexts: Set<UIOpenURLContext>) {
  guard let url = URLContexts.first?.url else { return }
  ButtonMerchant.trackIncomingURL(url)
}

// Handle Universal Links
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  ButtonMerchant.trackIncomingUserActivity(userActivity)
}
```

#### Objective-C
```objectivec
// Handle custom scheme urls
- (BOOL)application:(UIApplication *)app
	 openURL:(NSURL *)url
    options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {

[ButtonMerchant trackIncomingURL:url];

return YES;
}

// Handle Universal Links
- (BOOL)application:(UIApplication *)application
	 continueUserActivity:(NSUserActivity *)userActivity
    restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {

[ButtonMerchant trackIncomingUserActivity:userActivity];

return YES;
}
```

## Setup your Button Links domain  
### Xcode Entitlement  
Button uses Universal Links to open your app from the Button Links domain.

If you have't already, enable the [Associated Domains Capability](https://developer.apple.com/documentation/safariservices/supporting_associated_domains_in_your_app) and then add the following line to the list of domains.

#### Associated Domain
```text
applinks:yourdomain.bttn.io
```

### Button Dashboard Configuration  
Lastly, you’ll need to configure your [App Site Association file](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content/enabling_universal_links) and add your team identifier to the Button Dashboard.

- Navigate to the [Button Dashboard Apps Section](https://app.usebutton.com/merchant/integration-status/apps)
- Choose your iOS app and click it's name to drill in.
- Scroll down to the **Configurations** section and select **Add Manual Configuration**. If you've already added one, click **Edit** on the right side of that record.

#### Fully Qualified App ID
```text
<team_identifier>.com.example.app
```