aMapGeoFence
概述
注意：应工信部要求，自本插件1.1.0版本起首次调用本插件前必须先弹出隐私协议，详情参考SDK合规使用方案。之后需先调用 updateLocationPrivacy，否则定位接口都无效。
随着移动互联网飞速发展，人与手机成为了形影不离的好伙伴，围绕位置提供服务成为可能。LBS（location based service）应运而生，成为了各类APP的标配。
而定位则是实现一切LBS的基础——因为只有获取到用户的位置，才能围绕位置，为用户提供各类服务。
大家应该都有类似的经历，第一次打开一个APP，会弹出对话框，寻问是否可以使用您当前的位置。这就是我们通常说的定位功能。
定位能做什么？
1、获取用户实时位置信息，以便为其提供“附近”优质服务；
2、获取用户实时位置信息，设置地理围栏，实现信息的精准推送；
3、获得用户分布情况，通过位置大数据分析，实现高效的资源配置。
4、实时监测工作人员（专车、货运、快递、外卖等）的位置及运动轨迹，实现运力及人力的高效调度。
什么场景会用到定位？
移动互联时代，定位无处不在，任何一个应用，只要想知晓用户位置，就一定会用到定位（不管是为用户提供服务，还是用于用户分析）。 高德定位深植于各类APP中，出行、社交、O2O、P2P、旅游、新闻、天气……
1、定位可以配合地图一起使用
适用于需要定位用户当前位置，及周边人车、商户位置，并将其展示在地图上的应用，典型案例：美团、神州专车
2、定位也可以独立使用
适用于只需定位用户位置，或计算两个或多个位置间距离，无需在地图上展示的应用，典型案例：陌陌、58到家
定位的实现原理
据专家透露：同时打开手机自身的GPS定位，并开启WiFi开关（无需连接到WiFi），可以很好的提高定位精度。
小课堂：科普定位原理
为什么这样就可以提高定位精度？来，我们先来弄明白定位的原理吧！
目前，主流的手机定位方式大致分为三类：
1、GPS定位：通过手机中的GPS插件获取位置
2、基站定位：通过运营商的电信基站（2g、3g、4g等）进行定位
3、混合定位（也有叫wifi定位）：GPS+基站+wifi的混合定位方式
混合定位最为精确，高德采用的就是混合定位的方式。
我的APP如何实现定位功能呢？
定位对于APP，既然这么厉害且必须，那怎么才能在自己的APP中实现定位功能呢？
我们的 YonBuilder移动开发 平台已经将高德定位的 SDK 封装成了插件，开发者只需按照下述文档中所说的操作，简单几行代码即可实现负责的定位功能。
插件概述
aMapGeoFence 封装了高德定位的 SDK。包括定位功能和地理围栏功能。
使用插件前，请先注册高德开放平台账号。
申请 API Key
用户在使用本插件之前需要获取高德地图API Key，Key 申请的具体流程请参照 申请Key。本插件需要的 key 可以和 aMap、aMapLocation 、aMapNavigation 、aMapReportLocation 插件的 key 共用。
配置 config 文件
申请到 高德地图 API Key 后，需要配置在 config.xml 文件内。配置方法如下：
- 名称：aMapGeoFence
- 参数：apiKey
- 配置示例:
<feature name="aMapGeoFence">
<param name="android_api_key" value="3440f2cc7d0e5c4238641d245392eac6" />
<param name="ios_api_key" value="dd5343be258aa304698e42cd0fc761cd" />
</feature>
字段描述:
android_api_key：在高德地图开放平台申请的 android 版 ak android_api_key：在高德地图开放平台申请的 android 版 ak
ios_api_key：在高德地图开放平台申请的 iOS 版 ak
Android配置
<meta-data
name="com.amap.api.v2.apikey"
value="3440f2cc7d0e5c4238641d245392eac6" />
- 字段描述 name：固定值 value：在高德地图开放平台申请的 android 版 ak
注意：
在 iOS 平台上，若要支持后台定位需配置 config.xml 文件的 location 字段。
从1.0.6版本起，iOS 端 SDK 更新为高德最新版本SDK，最新版本的SDK包含 IDFA 相关功能。所以 iOS 端提交 AppStore 时必须认真阅读 提交AppStore必读，以及如何解决因获取 IDFA 被 AppStore 拒绝的问题？
插件接口
updateLocationPrivacy
设置定位类隐私权限
updateLocationPrivacy({params})
params
privacyAgree：
- 类型：字符串
- 描述：（可选项）用户同意隐私状态
- 默认值：didAgree
- 取值范围：
- didAgree：已同意
- notAgree；不同意
- unknow：未知
privacyShow:
- 类型：字符串
- 描述：（可选项）显示隐私弹窗状态
- 默认值：didShow
- 取值范围：
- didShow：已显示
- notShow；未显示
- unknow：未知
containStatus:
- 类型：字符串
- 描述：（可选项） 集成SDK隐私信息状态
- 默认值：didContain
- 取值范围：
- didContain：已集成
- notContain；未集成
- unknow：未知
示例代码
var aMap = api.require('aMapGeoFence');
aMap.updateLocationPrivacy({
privacyAgree:'didAgree',
privacyShow:'didShow',
containStatus:'didContain'
});
可用性
iOS系统，Android系统
可提供的1.1.0及更高版本
configManager
配置定位信息
configManager({params}, callback(ret))
params
accuracy：
- 类型：字符串
- 描述：设定定位精度
- 默认值：hundredMeters
- 取值范围：
- tenMeters：十米
- hundredMeters：百米
- kilometer：千米
- threeKilometers：三千米
- best：精确度最高
filter：
- 类型：数字
- 描述：位置更新所需最小距离（单位米）
- 默认值：1.0
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true //布尔类型；操作成功状态值
}
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.configManager({
accuracy: 'hundredMeters',
filter: 1
}, function(ret, err) {
if (ret.status) {
alert('定位管理器初始化成功！');
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
singleLocation
单次地理定位，可以通过 stopUpdatingLocation 方法去取消正在进行的单次定位请求。如果当前正在连续定位，调用此方法将会失败
singleLocation({params}, callback(ret, err))
params
timeout：
- 类型：数字
- 描述：指定单次定位超时时间，单位为妙（s）。最小值是2s
- 默认值：10
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true, //布尔类型；操作成功状态值
lon:116.213, //数字类型；定位到的经度
lat:39.213, //数字类型；定位到的纬度
accuracy: 65, //数字类型；本次定位的精度，
altitude: 200 //数字类型；当前设备所处的海拔信息
verticalAccuracy: 10 //数字类型；垂直位置精度，无效时为负数 （仅ios支持）
course: 200 //数字类型；偏离正北方向的角度，无效时为负数，范围 0.0 - 359.9
speed: 200 //数字类型；速度，无效时为负数，单位：m/s
floor: 2 //数字类型；在建筑物的第几层，无效时不返回
}
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.singleLocation({
timeout: 10
}, function(ret, err) {
if (ret.status) {
api.alert({msg: JSON.stringify(ret)});
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
singleAddress
单次逆地理定位，可以通过 stopUpdatingLocation 方法去取消正在进行的单次定位请求。如果当前正在连续定位，调用此方法将会失败
singleAddress({params}, callback(ret))
params
timeout：
- 类型：数字
- 描述：指定单次定位逆地理超时时间，单位为妙（s）。最小值是2s
- 默认值：5
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true, //布尔类型；操作成功状态值
address: {
formattedAddress: '', //字符串类型；格式化地址
country: '', //字符串类型；国家
province: '', //字符串类型；省/直辖市
city: '', //字符串类型；市
district: '', //字符串类型；区
township: '', //字符串类型；乡镇(android不支持)，已废弃，建议用aMap插件的getNameFromCoords接口获取
neighborhood: '', //字符串类型；社区(android不支持)，已废弃，建议用aMap插件的getNameFromCoords接口获取
building: '', //字符串类型；建筑(android不支持)，已废弃，建议用aMap插件的getNameFromCoords接口获取
citycode: '', //字符串类型；城市编码
adcode: '', //字符串类型；区域编码
street: '', //字符串类型；街道名称
number: '', //字符串类型；门牌号
POIName: '', //字符串类型；兴趣点名称
AOIName: '' //字符串类型；所属兴趣点名称
}
}
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.singleAddress({
timeout: 10
}, function(ret, err) {
if (ret.status) {
api.alert({msg: JSON.stringify(ret)});
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
startLocation
开始连续定位，可以通过 stopUpdatingLocation 方法去取消。调用此方法会cancel掉所有的单次定位请求
startLocation(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
status:true, //布尔类型；操作成功状态值
lon:116.213, //数字类型；经度
lat:39.213, //数字类型；纬度
accuracy: 65, //数字类型；本次定位的精度，
altitude: 200 //数字类型；当前设备所处的海拔信息
verticalAccuracy: 10 //数字类型；垂直位置精度，无效时为负数 （仅ios支持）
course: 200 //数字类型；偏离正北方向的角度，无效时为负数，范围 0.0 - 359.9
speed: 200 //数字类型；速度，无效时为负数，单位：m/s
floor: 2 //数字类型；在建筑物的第几层，无效时不返回
}
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.startLocation(function(ret, err) {
if (ret.status) {
api.alert({msg: JSON.stringify(ret)});
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
stopUpdatingLocation
停止连续定位，调用此方法会cancel掉所有的单次定位请求，可以用来取消单次定位
stopUpdatingLocation()
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.stopUpdatingLocation();
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addKeywordPOIRegion
根据关键字创建POI围栏
addKeywordPOIRegion({params})
params
keyword：
- 类型：字符串
- 描述：要查询的关键字，多个关键字用“|”分割
- 默认值：无
type：
- 类型：字符串
- 描述：要查询的POI类型，多个类型用“|”分割。具体分类编码和规则
- 默认值：无
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
city：
- 类型：字符串
- 描述：（可选项）要查询的城市
- 默认值：无
size：
- 类型：数字
- 描述：（可选项）要查询的数据的条数，(0,25]，传入<=0的值为10，传入大于25的值为25，默认10
- 默认值：10
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addKeywordPOIRegion({
keyword: '北京大学',
type: '高等院校',
customID: '111',
city: '北京',
size: 20,
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addAroundPOIRegion
根据经纬度进行周边搜索创建POI围栏
addAroundPOIRegion({params})
params
location：
- 类型：JSON 对象
- 描述：点的经纬度坐标，必填
- 内部字段：
{
latitude: 0, // 数字类型；纬度；默认值：无
longitude: 0, // 数字类型；经度；默认值：无
}
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
keyword：
- 类型：字符串
- 描述：（可选项）要查询的关键字，多个关键字用“|”分割
- 默认值：无
type：
- 类型：字符串
- 描述：（可选项）要查询的POI类型，多个类型用“|”分割
- 默认值：无
aroundRadius：
- 类型：数字
- 描述：（可选项）查询半径，单位：米，(0,50000]，超出范围取3000，默认3000
- 默认值：3000
size：
- 类型：数字
- 描述：要查询的数据的条数，(0,25]，传入<=0的值为10，传入大于25的值为25，默认10
- 默认值：10
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addAroundPOIRegion({
location:{
latitude:39.908692,
longitude:116.397477
},
keyword: '肯德基',
type: '050301',
customID: '222',
aroundRadius: 10000,
size: 20,
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addDistrictRegion
创建行政区域围栏
addDistrictRegion({params})
params
districtName：
- 类型：字符串
- 描述：行政区域关键字，必填，只支持单个关键词语：行政区名称、citycode、adcode。规则
- 默认值：无
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addDistrictRegion({
districtName: '海淀区',
customID: '333'
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addCircleRegion
创建自定义圆形围栏
addCircleRegion({params})
params
center：
- 类型：JSON 对象
- 描述：围栏的中心点经纬度坐标
- 内部字段：
{
latitude: 0, // 数字类型；纬度；默认值：无
longitude: 0, // 数字类型；经度；默认值：无
}
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
radius：
- 类型：数字
- 描述：（可选项）围栏的半径，单位：米，要求大于0
- 默认值：3000
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addCircleRegion({
center:{
latitude:39.908692,
longitude:116.397477
},
radius: 300,
customID: '444'
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addPolygonRegion
创建自定义多边形围栏
addPolygonRegion({params})
params
coordinates：
- 类型：数组
- 描述：经纬度坐标点数据，经纬度坐标点的个数不可小于3个
- 内部字段：
[
{
latitude: 0, // 数字类型；纬度；默认值：无
longitude: 0, // 数字类型；经度；默认值：无
}
]
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addPolygonRegion({
coordinates:[
{
latitude:39.933921,
longitude:116.372927
},
{
latitude:39.907261,
longitude:116.376532
},
{
latitude:39.900611,
longitude:116.418161
},
{
latitude:39.941949,
longitude:116.435497
}
],
customID: '555'
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
removeGeoFence
根据customID移除围栏
removeGeoFence({params})
params
customID：
- 类型：字符串
- 描述：用户自定义ID
- 默认值：无
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.removeGeoFence({
customID: '555'
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
removeAllGeoFence
移除所有围栏
removeAllGeoFence()
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.removeAllGeoFence();
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
addGeoFenceEventListener
添加监听
addGeoFenceEventListener(callback(ret))
callback(ret)
ret：
- 类型：JSON 对象
- 内部字段：
{
customID:'111', //字符串类型；用户添加围栏的传入的自定义ID
fenceId:'', //字符串类型；围栏Id（仅Android支持）
status: //字符串类型；围栏的状态
//取值范围：
//'add' : 添加围栏（仅ios支持）
//'inside' : 进入围栏
//'outside' : 退出围栏
//'stayed' : 在围栏内停留
//'unknown' : 未知
}
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.addGeoFenceEventListener(function(ret) {
if (ret) {
api.alert({msg: JSON.stringify(ret)});
}
});
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本
removeGeoFenceEventListener
移除监听
removeGeoFenceEventListener()
示例代码
var aMapGeoFence = api.require('aMapGeoFence');
aMapGeoFence.removeGeoFenceEventListener();
可用性
iOS系统，Android系统
可提供的1.0.0及更高版本