店滴开发者手册店滴开发者手册
首页
指南
插件
接口
智能设备
element后台
SDK
首页
指南
插件
接口
智能设备
element后台
SDK
  • SDK

    • 指南
    • Uni-app SDK
    • Uni-app SDK
    • 安装与配置
    • 主 SDK 接口文档
    • 快速开始
    • WebSocket 类详细文档
    • PHP SDK文档
    • 物联网PHP SDK使用指南

主 SDK 接口文档

概述

主 SDK (index.js) 是整个 JavaScript SDK 的入口点,整合了 HTTP 请求、WebSocket 通信、权限管理等多个子模块,提供了统一的 API 接口。

主要属性

ddiot 对象

const ddiot = {
  // API 函数集合
  ...apiFunc,
  ...adminFunc,
  
  // 基础属性
  bloc_id: 0,                           // 区域ID
  request: sendHttp,                     // HTTP 请求实例
  websocket: null,                      // WebSocket 实例
  websocketConf: null,                  // WebSocket 配置
  permission: permission,               // 权限管理
  iglobal: iglobal,                     // 全局变量
  uploadImgUrl: '',                     // 图片上传地址
  apiBsaeUrl: '',                       // API 基础地址
  imgBaseUrl: '',                       // 图片基础地址
  siteUrl: '',                          // 站点地址
  WECHAT_LOGIN: true,                   // 微信登录开关
  WECHAT_AUTH_BACK_URL: 'WECHAT_AUTH_BACK_URL', // 微信授权回调URL
  
  // H5 环境下的微信 JS SDK
  // #ifdef H5
  jweixin: jweixin,
  // #endif
}

初始化方法

install 方法

install(vueInstance, extra = {})

初始化 SDK 并将其安装到 Vue 实例上。

参数说明

参数类型默认值说明
vueInstanceVue Instance-Vue 实例
extraObject{}额外配置

extra 配置说明

属性类型必填说明
httpObject是HTTP 配置
websocketConfObject否WebSocket 配置

WebSocket 配置要求

WebSocket 配置必须包含以下参数:

  • url: WebSocket 服务器地址
  • authUrl: 认证服务器地址
  • heartRateType: 心跳类型
  • heartRate: 心跳间隔
  • app_id: 应用ID

使用示例

// 在 main.js 中使用
app.use(ddiot, {
  websocketConf: {
    url: "wss://iot.ddicms.com:9502/addons",
    authUrl: 'wss://iot.ddicms.com:9502/auth',
    heartRateType: 'heart',
    heartRate: 20000,
    app_id: 'your_app_id',
    app_secret: 'your_app_secret',
  },
  http: {
    successCode: 200,
    apiConfig: {
      bloc_id: 1,
      store_id: 1,
      baseUrl: 'https://api.example.com',
      // ... 其他配置
    }
  }
})

WebSocket 相关方法

createSocket 方法

createSocket(route = 'addons')

创建 WebSocket 连接。

参数说明

参数类型默认值说明
routeString'addons'路由类型

返回值

返回一个 Promise,解析为 WebSocket 实例。

使用示例

// 创建 WebSocket 连接
const createWebSocket = async () => {
  try {
    const socket = await ddiot.createSocket('addons')
    console.log('WebSocket 创建成功:', socket)
    ddiot.websocket = socket
  } catch (error) {
    console.error('WebSocket 创建失败:', error)
  }
}

closeSocket 方法

closeSocket()

关闭 WebSocket 连接并清理实例。

HTTP 请求方法

request 方法

request(url, method, data, loading = false, header = {})

发起 HTTP 请求。

参数说明

参数类型默认值说明
urlString-请求URL
methodString-请求方法 (GET, POST, PUT, DELETE 等)
dataObject{}请求数据
loadingBooleanfalse是否显示加载动画
headerObject{}请求头

使用示例

// 获取设备组数据
const getDeviceData = async (deviceMac) => {
  try {
    const response = await ddiot.request('/device/deviceGroup', 'POST', {
      device_mac: deviceMac
    }, true, {
      scene: 'iot'
    })
    return response.data
  } catch (error) {
    console.error('请求失败:', error)
  }
}

辅助方法

toast 方法

toast(text, duration, success)

显示 Toast 提示。

参数说明

参数类型默认值说明
textString"出错啦~"提示文本
durationNumber2000显示时长
successBooleanfalse是否显示成功图标

使用示例

ddiot.toast('操作成功', 2000, true)

modal 方法

modal(title, content, showCancel, callback, confirmColor, confirmText)

显示模态对话框。

参数说明

参数类型默认值说明
titleString'提示'标题
contentString-内容
showCancelBoolean-是否显示取消按钮
callbackFunction-回调函数
confirmColorString"#5677fc"确认按钮颜色
confirmTextString"确定"确认按钮文本

使用示例

ddiot.modal('确认操作', '您确定要执行此操作吗?', true, (confirm) => {
  if (confirm) {
    // 执行确认操作
  }
})

平台检测方法

isAndroid

isAndroid()

检测是否为 Android 平台。

isPhoneX

isPhoneX()

检测是否为 iPhone X 系列设备。

时间相关方法

logTime

logTime(remark)

记录当前时间戳。

参数说明

参数类型说明
remarkString备注信息

使用示例

ddiot.logTime('开始执行操作')
// ... 执行某些操作
ddiot.logTime('操作完成')

登录状态相关方法

isLogin

isLogin()

检查是否已登录。

getToken

getToken()

获取访问令牌。

getRefToken

getRefToken()

获取刷新令牌。

工具函数

constNum

constNum()

返回特定平台的常量值。

HTTP 配置

配置结构

{
  successCode: 200,  // 成功状态码
  apiConfig: {
    bloc_id: 1,      // 区域ID
    store_id: 1,     // 商店ID
    baseUrl: '',     // API 基础URL
    siteUrl: '',     // 站点URL
    uploadImgUrl: '', // 上传图片URL
    imgBaseUrl: '',  // 图片基础URL
    headerFunc: (config) => {}, // 请求头生成函数
    beforRequest: (config) => {}, // 请求前处理函数
    getToken: () => {}, // 获取令牌函数
    getRefToken: () => {}, // 获取刷新令牌函数
    refTokenCallBack: (res) => {}, // 刷新令牌回调函数
  },
  responseSuccessCallBack: (res) => {}, // 响应成功回调
  apiList: [], // API 列表
}

请求拦截器

beforRequest

在请求发送前对配置进行处理。

beforRequest: (config) => {
  const token = uni.getStorageSync('access_token')
  const whiteList = ['/wechat/decrypt/msg', '/wechat/basics/signup']

  if (whiteList.some(path => config.url.includes(path))) {
    return config
  }

  if (!token) {
    // 未登录处理
    uni.reLaunch({
      url: '/pages/login/index'
    })
    return Promise.reject(config)
  }

  return config
}

responseSuccessCallBack

处理响应成功后的逻辑。

responseSuccessCallBack: (res) => {
  if (res && (res.code === 403 || res.code === 402)) {
    // 登录过期处理
    uni.removeStorageSync('access_token')
    uni.reLaunch({
      url: '/pages/login/index'
    })
  } else if (res.code !== 200) {
    // 其他错误处理
    uni.showModal({
      title: '提示',
      content: res.message,
      showCancel: false
    })
  }
}

权限管理

SDK 集成了权限管理模块,支持不同平台的权限申请。

// 使用权限管理
const checkPermission = async () => {
  const result = await ddiot.permission('location')
  if (result) {
    // 有权限,执行相关操作
  } else {
    // 无权限,引导用户授权
  }
}

实际应用示例

页面中使用 SDK

// 在 Vue 组件中使用
import { getCurrentInstance } from 'vue'

export default {
  setup() {
    const { proxy } = getCurrentInstance()
    const $ddiot = proxy.$ddiot
    
    // 获取设备数据
    const fetchDeviceData = async (mac) => {
      try {
        const response = await $ddiot.request('/device/info', 'GET', { mac })
        return response.data
      } catch (error) {
        console.error('获取设备数据失败:', error)
      }
    }
    
    // 初始化 WebSocket
    const initWebSocket = async () => {
      try {
        const ws = await $ddiot.createSocket()
        $ddiot.websocket = ws
        
        // 监听消息
        ws.on('device_status', (data) => {
          console.log('设备状态更新:', data)
        })
      } catch (error) {
        console.error('WebSocket 初始化失败:', error)
      }
    }
    
    return {
      fetchDeviceData,
      initWebSocket
    }
  }
}

全局配置示例

// main.js 中的完整配置
export function createApp() {
  const app = createSSRApp(App)
  
  // 全局挂载
  app.config.globalProperties.$ddiot = ddiot

  app.use(ddiot, {
    websocketConf: {
      url: "wss://your-server.com/addons",
      authUrl: 'wss://your-server.com/auth',
      heartRateType: 'heartbeat',
      heartRate: 30000,
      app_id: 'your_app_id',
      app_secret: 'your_app_secret',
    },
    http: {
      successCode: 200,
      apiConfig: {
        bloc_id: 1,
        store_id: 1,
        baseUrl: 'https://api.your-domain.com',
        siteUrl: 'https://your-domain.com',
        uploadImgUrl: 'https://api.your-domain.com/upload',
        imgBaseUrl: 'https://your-domain.com/images/',
        headerFunc: (config) => {
          return {
            'bloc-id': uni.getStorageSync('bloc-id') || 1,
            'store-id': uni.getStorageSync('store-id') || 1,
            'access-token': uni.getStorageSync('access_token') || ''
          }
        },
        beforRequest: (config) => {
          // 请求前处理逻辑
          return config
        },
        getToken: () => uni.getStorageSync('access_token'),
        getRefToken: () => uni.getStorageSync('refresh_token'),
        refTokenCallBack: (res) => {
          // 刷新令牌回调
          uni.setStorageSync('access_token', res.data.access_token)
        }
      },
      responseSuccessCallBack: (res) => {
        // 响应处理逻辑
        if (res.code !== 200) {
          uni.showToast({
            title: res.message,
            icon: 'none'
          })
        }
      }
    }
  })

  return { app }
}

注意事项

  1. 初始化时机: 确保在使用 SDK 功能前已完成初始化
  2. 错误处理: 始终包含适当的错误处理逻辑
  3. 资源清理: 在适当的时候清理 WebSocket 连接和其他资源
  4. 安全性: 敏感信息如 app_secret 应妥善保管
  5. 平台差异: 注意不同平台间的差异,使用条件编译处理
  6. 版本兼容性: 关注 SDK 版本更新,及时适配新功能
Prev
安装与配置
Next
快速开始