# Beacon management

## **Pair a beacon to a vehicle**

The following function allows you to create a logical pairing between a beacon and a vehicle. The results of data analysis containing a beacon will be assigned to the vehicle to which the beacon has been paired with.

```swift
func addBeacon(
    vehicleId: String,
    beacon: DKBeacon,
    completionHandler: @escaping (DKVehicleBeaconStatus) -> Void
)
```

This method have the following parameters:

<table><thead><tr><th width="165.33333333333331">Name</th><th width="151">Type</th><th>Description</th></tr></thead><tbody><tr><td>beacon</td><td><a href="../references-ios#dkbeacon">DKBeacon</a></td><td>The beacon data you want to pair to the vehicle</td></tr><tr><td>vehicleId</td><td>String</td><td>The identifier of vehicle that you wish to pair with a beacon</td></tr></tbody></table>

remark: All fields are required. If you don't know the uniqueId of your beacons, just add an empty field.

Check the `DKVehicleBeaconStatus` value to ensure your beacon is correctly paired:

<table><thead><tr><th width="257">Value</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>The beacon has been successfully paired to the specified vehicle. The vehicle data in the local database is automatically updated.</td></tr><tr><td>error</td><td>An error occurred when trying to pair the beacon to the vehicle, for example if the user has no network during when the method is called.</td></tr><tr><td>unknownVehicle</td><td>An error occurred: the specified vehicle does not belong to the user.</td></tr><tr><td>unavailableBeacon</td><td>The provided beacon is currently paired to another vehicle. You must unpair the beacon to that vehicle before in order to pair it to your desired vehicle.</td></tr></tbody></table>

## **Replace the beacon of a vehicle**

If a beacon is already paired with a vehicle, it can be replaced. The following function is used to change the beacon paired with a vehicle:

```swift
func changeBeacon(
    vehicleId: String,
    oldVehicleId: String,
    beacon: DKBeacon,
    completionHandler: @escaping (DKVehicleBeaconStatus) -> Void
)
```

This method have the following parameters:

<table><thead><tr><th width="202.33333333333331">Name</th><th width="144">Type</th><th>Description</th></tr></thead><tbody><tr><td>beacon</td><td><a href="../references-ios#dkbeacon">DKBeacon</a></td><td>The new beacon data you want to pair to the vehicle.</td></tr><tr><td>vehicleId</td><td>String</td><td>The identifier of the vehicle for which you wish to change the beacon</td></tr><tr><td>oldVehicleId</td><td>String</td><td>The identifier of the old vehicle paired to the beacon</td></tr></tbody></table>

remark: All fields are required. If you don't know the uniqueId of your beacons, just add an empty field.

Check the `DKVehicleBeaconStatus` value to ensure your beacon is correctly changed:

<table><thead><tr><th width="244">Value</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>The beacon has been successfully replaced for the specified vehicle. The vehicles data in the local database are automatically updated.</td></tr><tr><td>error</td><td>An error occurred when trying to replace the beacon of the vehicle.</td></tr><tr><td>unknownVehicle</td><td>An error occurred: the specified vehicle does not belong to the user.</td></tr><tr><td>unavailableBeacon</td><td>The provided beacon is currently paired to another vehicle. You must unpair the beacon to that vehicle before in order to pair it to your desired vehicle.</td></tr></tbody></table>

## **Unpair the beacon from a vehicle**

The following function can be used to delete the pairing between a beacon and a vehicle:

```swift
func removeBeacon(
    vehicleId: String,
    completionHandler: @escaping (DKVehicleBeaconRemoveStatus) -> Void
)
```

This method have the following parameter:

<table><thead><tr><th width="173.33333333333331">Name</th><th width="137">Type</th><th>Description</th></tr></thead><tbody><tr><td>vehicleId</td><td>String</td><td>The identifier of the vehicle for which you want to unpair the beacon.</td></tr></tbody></table>

Check the `DKVehicleBeaconRemoveStatus` value to ensure your beacon is correctly unpaired:

<table><thead><tr><th width="286">Value</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>The beacon has been successfully removed from the specified vehicle. The vehicle data in the local database is automatically updated.</td></tr><tr><td>error</td><td>An error occurred when trying to remove the beacon of the vehicle.</td></tr><tr><td>unknownVehicle</td><td>An error occurred: the specified vehicle does not belong to the user.</td></tr></tbody></table>