aMapReportLocation

来自于:开发者立即使用

概述

aMapReportLocation 封装了将定位坐标上报给指定服务器的相关接口,本模块定位功能是集成的高德地图移动端定位开放 SDK,所以模块获取到的坐标也是属于高德地图坐标系。

本模块最大的特点是,开发者可自定义设置定位精度以及上报服务器时间间隔。亦可自定义设置上报数据的请求头信息,详情请参考模块接口参数。

申请 API Key

用户在使用本模块之前需要获取高德地图API Key,Key 申请的具体流程请参照 申请Key。本模块需要的 key 可以和 aMapaMapLBSation 模块的 key 共用。

注意:

1. 使用此模块之前必须先配置 config 文件


针对 iOS 平台配置方法:

  • 名称:aMapReportLocation
  • 参数:apiKey
  • 配置示例:
  <feature name="aMapReportLocation">
    <param name="ios_api_key" value="高德ak" />
  </feature>

针对 android 平台配置方法:

  • 配置示例:
 <meta-data
     name="com.amap.api.v2.apikey"
     value="高德ak" />

2. 后台定位上报功能

由于系统限制,在 iOS 平台上,定位功能必须在 app 为当前激活使用状态或后台运行状态时才能正常运行。所以若要集成后台定位功能,必须得配置 config 文件 以申请后台运行权限,然后云编译或自定义 loader 方可正常使用。配置实例如下:

//配置一个后台定位功能:
<preference name="backgroundMode" value="location"/>

//配置多个后台运行功能,各值之间用竖线 | 隔开:
<preference name="backgroundMode" value="location | audio"/>

用户在使用本模块之前需要获取高德地图API Key,Key 申请的具体流程请参照 申请Key。本模块需要的 key 可以和 aMapaMapLBSaMapLocationaMapNavigation 模块的 key 共用。

模块接口

startLocation

开始定位并上报指定服务器

startLocation({params}, callback(ret, err))

params

accuracy:

  • 类型:字符串
  • 描述:(可选项)定位精度,信号不稳定时,定位精度过高,在 iOS 平台上会偶现定位失败的问题
  • 默认值:device_sensors
  • 取值范围:
    • battery_saving:低功耗模式
    • device_sensors:仅设备(Gps)模式
    • hight_accuracy:高精度模式

filter:

  • 类型:数字
  • 描述:(可选项)位置更新所需最小距离(单位米)
  • 默认值:1.0

autoStop:

  • 类型:布尔
  • 描述:(可选项)获取到位置信息后是否自动停止定位
  • 默认值:true

report:

  • 类型:JSON 对象
  • 描述:(可选项)当 autoStop 为 false 时,本参数表示将当前位置信息上报的配置,若 autoStop 为 true,则本参数无意义。
  • 内部字段:
{      
    url: '',          //(可选项)字符串类型;要上报的服务器地址,支持 http、https 协议;若不传则本接口仅有回调函数,不上报服务器。
    uid: '',          //字符串类型;上报数据时携带的用户id(用于服务器端唯一标识用户)
    interval:         //(可选项)数字类型;将当前位置信息上报给指定服务器间隔时间,单位为妙(s);默认:30
    type: 'post',     //(可选项)字符串类型;上报的方式;默认值:post;
                      // 取值范围如下:
                      // post:将位置信息 post 到服务器
                      // get:将位置信息以 get 的形式发送给服务器
    headerField: {    //(可选项)JSON对象;当 type 为 post 时,本参数表示设置请求头信息
       //本参数的内容格式为:key:value,如下demo:
       timestamp: '12345677890',//如果检测到有 key 为 timestamp 则模块会在每次上报时获取当前时间戳作为 timestamp 的 value 设置给本次 post 请求的请求头信息
       ContentType: 'text/plain',
       custid: '123456',
       Accept: '*/*'      
    },
    aesKey: ''       //(可选项)字符串类型;是否将 post 的数据进行 AES 加密,若不传则不加密,若本字段有值则进行 AES 加密,加密模式和填充模式分别为:CBC/PKCS7Padding;初始iv为:{0xA,1,0xB,5,4,0xF,7,9,0x17,3,1,6,8,0xC,0xD,91}
}

上报的数据格式如下:

{
    loc: {                    //JSON对象;上报的当前位置信息
        lon: 116.213,         //数字类型;经度
        lat: 39.213           //数字类型;纬度
    },
    uid: '',                  //字符串类型;开发者自定义的用户id(通过startLocation接口传给模块)
    accuracy: 65,             //数字类型;本次定位的精度,仅支持 iOS 平台
    timestamp: 1396068155591, //数字类型;定位此位置信息时的时间戳
    altitude: 200             //数字类型;当前设备所处的海拔信息
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,             //布尔类型;操作成功状态值,true|false
    loc: {                    //JSON对象;当前位置信息
        lon: 116.213,         //数字类型;经度
        lat: 39.213,          //数字类型;纬度
    },
    accuracy: 65,             //数字类型;本次定位的精度,仅支持 iOS 平台
    timestamp: 1396068155591, //数字类型;定位的时间戳
    altitude: 200             //数字类型;当前设备所处的海拔信息
}

示例代码

var aMapReportLocation = api.require('aMapReportLocation');
aMapReportLocation.startLocation({
    accuracy: 'battery_saving',
    filter: 100,
    autoStop: false,
    report: {
        uid: '123456789',
        url: "https://",
        interval: 30,
        type: 'post',
        headerField: {
           timestamp: '',
           ContentType: 'text/plain',
           custid: '123456',
           Accept: '*/*'
         }, 
         aesKey: 'apicloud'
    }
}, function(ret) {
    if (ret.status) {
        api.alert({ msg: JSON.stringify(ret) });
    } else {
        api.alert({ msg: '定位失败' });
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopLocation

停止定位,当调用 startLocation 接口时 autoStop 参数传 false,则调用本接口可停止定位功能

stopLocation()

示例代码

var aMapReportLocation = api.require('aMapReportLocation');
aMapReportLocation.stopLocation();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本