Mild White Pet Health Open Platform Developer Documentation

Welcome to Mild White Pet Health Open Platform. You can quickly access the platform through this document to obtain pet health data such as heart rate, respiration, and in-bed status.

Platform Introduction

Mild White Pet Health Open Platform provides standardized pet health data interfaces for third-party developers, supporting device binding, historical data query, real-time data push and other capabilities to help you quickly build pet health related applications.

Platform Capabilities

• 🔐 Secure Authentication: Based on OAuth2.0 client mode to ensure interface call security
• 📱 Multi-platform SDK: Provides SDKs for Android, iOS, HarmonyOS, Flutter, UniAppX, Python and more
• ⚡ Real-time Push: Millisecond-level push of pet health real-time data based on MQTT protocol
• 📊 Historical Data: Support querying historical health data reported by devices, returned in pages
• 🔒 Permission Isolation: Strict application data isolation, each application can only access its own bound device data

Integration Process

1. Register an open platform developer account and complete enterprise qualification certification
2. Obtain SDKAppID and AppSecret credentials after approval
3. Call the OAuth2.0 interface to obtain access_token
4. Call the device binding interface to bind the device SN with third-party users/pets
5. Query historical data through HTTP interface, or subscribe to real-time data through MQTT

Apply for Developer Credentials

Visit Mild White Open Platform, register an account and submit an enterprise qualification application. After approval, you will get your exclusive SDKAppID and AppSecret as identity credentials for interface calls.

Please keep your AppSecret properly and do not expose it in client code to avoid leakage.

OAuth2.0 Authentication

The platform uses OAuth2.0 Client Credentials mode for interface authentication. All open API calls need to carry access_token.

Authentication Process

1. Use SDKAppID and AppSecret to call the token interface to obtain access_token
2. access_token is valid for 2 hours, need to re-obtain after expiration
3. When calling business interfaces, carry Authorization: Bearer {access_token} in the request header

Get access_token

Endpoint: GET/POST https://open.aidbai.com/oauth/token

Request Parameters:

Response Example:

{
  "code": 1,
  "msg": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}

API Reference

All business interface request headers must carry Authorization: Bearer {access_token}, otherwise 401 unauthorized error will be returned.

Allocate Third-party User Code

Allocate a platform-unique ThirdUserCode for third-party system users for device binding and data association.

Endpoint: POST https://open.aidbai.com/open/api/allocateThirdUserCode

Response Example:

{
  "code": 1,
  "msg": "success",
  "data": {
    "third_user_code": "TU_61a8f9d7e4b0c2a3f1e2d3c4"
  }
}

Device Binding

Bind the device SN with third-party users and pets. After binding, the device data will be pushed to the current application.

Endpoint: POST https://open.aidbai.com/open/api/bindDevice

Request Parameters (JSON):

Device Unbinding

Unbind the device from the third-party user, data push will stop after unbinding.

Endpoint: POST https://open.aidbai.com/open/api/unbindDevice

Request Parameters (JSON):

Query Device Historical Data

Query historical health data reported by devices in pages.

Endpoint: GET https://open.aidbai.com/open/api/history

Request Parameters:

Query Device Ownership

Query the current binding ownership information of the device.

Endpoint: GET https://open.aidbai.com/open/api/getDeviceOwner

Request Parameters:

MQTT Real-time Data Access

The platform provides real-time data push service based on MQTT protocol. Health data reported by devices will be pushed to subscribed third-party applications in real time.

Connection Information

Subscription Rules

1. Permission Isolation: Each application can only subscribe to open/app/{your SDKAppID}/realtime topic, cross-application subscriptions are automatically rejected
2. Wildcards Prohibited: Subscriptions using wildcards such as # and + are not allowed and will be directly rejected
3. Publishing Prohibited: Third-party clients are only allowed to subscribe to messages, and are not allowed to publish messages to any topic
4. Connection Limit: Each SDKAppID supports up to 10 long connections by default, contact customer service for more connections

Message Format

All real-time messages are in JSON format (UTF-8 encoding), field descriptions are as follows:

Integration Example

Python Example (paho-mqtt):

import paho.mqtt.client as mqtt
import json

BROKER = "mqtt.aidbai.com"
PORT = 1883
SDK_APP_ID = "YOUR_SDK_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
TOPIC = f"open/app/{SDK_APP_ID}/realtime"

def on_connect(client, userdata, flags, rc):
    print(f"Connected successfully, result code: {rc}")
    client.subscribe(TOPIC, qos=1)

def on_message(client, userdata, msg):
    payload = json.loads(msg.payload.decode('utf-8'))
    print(f"Message received: {payload}")

client = mqtt.Client(client_id=f"python_server_{SDK_APP_ID}", clean_session=False)
client.username_pw_set(SDK_APP_ID, APP_SECRET)
client.on_connect = on_connect
client.on_message = on_message
client.connect(BROKER, PORT, 60)
client.loop_forever()

SDK Download

We provide multi-platform SDKs to help you quickly access the platform:

Error Code Description

All interfaces return a unified JSON format, code=1 means success, other values mean failure:

FAQ

1. HTTP interface call returns 401 error?

• Check if access_token is correct and not expired (valid for 2 hours)
• Check if the Authorization header format is Bearer {access_token}, note there is a space after Bearer
• Check if access_token corresponds to the current SDKAppID

2. MQTT connection failed?

• Check if Broker address and port are correct: mqtt.aidbai.com:1883
• Check if username and password are correct, username is SDKAppID, password is AppSecret
• Check if the server network can access port 1883, and if the firewall is open
• Check if the number of connections exceeds the limit, default maximum 10 connections per application

3. MQTT subscription failed?

• Check if the subscription topic is correct, format must be open/app/{your SDKAppID}/realtime
• Wildcard subscriptions are not supported, subscribing to other application topics is not allowed
• Third-party clients are not allowed to publish messages, only subscribe

4. Not receiving real-time data?

• Check if the device is bound to the current application
• Check if the device is online and reporting data normally
• Check if MQTT connection is normal and subscription is successful
• Check if QoS level is set to 1 to avoid message loss