# device SDK

## Introduction

\
The Device SDK is designed to prevent cheating from non-BitBoy devices. When used in conjunction with backend device verification services, it can verify whether the source is a legitimate BitBoy device, thereby ensuring a trusted dApp running environment and maintaining the security of the ecosystem.

## Main Features

* **Device SDK signs device information**
* **Device Verify validates signatures**

## Main Steps

<figure><img src="https://2258306204-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fhq5vqnDNMVFPDrz1Ucu4%2Fuploads%2F1s2HIJnjFVL8dkazc2wW%2Fimage.png?alt=media&#x26;token=05f1f9c9-bf69-44f9-81db-b3db5d316f3e" alt=""><figcaption><p>Process diagram for dAPP to verify that a device request is trusted</p></figcaption></figure>



### Step Description

1. When a dApp needs to verify if the device is a genuine BitBoy device (such as preventing requests from virtual machines or maliciously forged requests from non-BitBoy terminals), call the integrated device SDK in the dApp to obtain device signature and other information;
2. When sending requests, the dApp can include the device signature information obtained in step 1 and send it to the business backend server (maintained by developers);
3. The business backend server constructs specific requests and calls the BitBoy Device Verification Service API to obtain verification results.

{% hint style="danger" %}
These steps are only necessary when device identity verification is required (to avoid resource waste and occupation, the BitBoy Device Verification Service has call limitations and should not be called arbitrarily. It is recommended to **use it only during necessary business processes**).
{% endhint %}





## Detailed Instructions&#x20;

### Usage Guide

1. **Apply and obtain app\_key from the** [**BitBoy Developer Application Management Console**](../getting-started/introduction/developer-console)**.**
2. **Initialize SDK**&#x20;

Before using the SDK, you need to obtain an APP\_KEY from the Developer Console. This is your application's unique identifier.

```java
//sample code
BitboySDK sdk = new BitboySDK(context, "YOUR_APP_KEY");
```

3. **Generate Signature**&#x20;

When signature operation is needed, call the SDK's signing method:

```java
//sample code
String signature = sdk.signMessage();
```

This method will return a signature string containing all necessary information.

{% hint style="info" %}
Signatures cannot be reused. A new signature must be generated each time verification is required.
{% endhint %}

4. **Sending Signature to Verification Server**&#x20;

When sending requests to the BitBoy server, add the signature to the request header:

```java
// sample code
HttpURLConnection connection = (HttpURLConnection) url.openConnection(); 
connection.setRequestProperty("message", signature); 
connection.setRequestProperty("sign", sdk.getSignature());
```

{% hint style="success" %}
Please refer to [the code example of Device SDK integration using React Native ](device-sdk/example-react-native-integration-with-device-sdk)as an example
{% endhint %}



## Important Notes

* Please keep your **APP\_KEY** secure and do not expose it or hard-code it in your application.
* The signature verification service has usage limits and doesn't need to be called every time. **Avoid frequent calls** - it's recommended to use it only when necessary or cache results for a certain period.
* The signature result includes timestamp information to prevent replay attacks. **Please ensure to use the generated signature promptly.**

## Error Handling

The SDK may throw the following exceptions:

* **InvalidAppKeyException:** Thrown when the provided app\_key is invalid.
* **SignatureFailedException:** Thrown when the signature process fails.\
  Please ensure proper handling of these exceptions when using the SDK.

## Support

If you encounter any issues while using the SDK, please contact the BitBoy Developer Support Team.

