Geozones API

getNearestZone

由 SDK 内部调用。检索最近地理区域的参数及其距离。同时记录设备位置以用于地理推送通知。

POST https://api.pushwoosh.com/json/1.3/getNearestZone

请求正文参数

参数	类型	必需	描述
application	`string`	是	Pushwoosh 应用程序代码
hwid	`string`	是	在 `/registerDevice` 请求中使用的硬件设备 ID。
lat	`string`	是	设备的纬度。
lng	`string`	是	设备的经度。

请求示例

{
  "request": {
    "application": "APPLICATION_CODE",
    "hwid": "HWID",
    "lat": 10.12345,
    "lng": 28.12345
  }
}

PHP 示例

// See http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html

use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;

// Creates the request instance
$request = GetNearestZoneRequest::create()
    ->setHwid('HWID')
    ->setLat(10.12345)
    ->setLng(28.12345);

// Call the '/getNearestZone' Web Service
$response = $pushwoosh->getNearestZone($request);

if ($response->isOk()) {
    print 'Zone name : ' . $response->getResponse()->getName();
    print 'Latitude : ' . $response->getResponse()->getLat();
    print 'Longitude : ' . $response->getResponse()->getLng();
    print 'Range : ' . $response->getResponse()->getRange();
    print 'Distance : ' . $response->getResponse()->getDistance();
} else {
    print 'Oops, the operation failed :-(';
    print 'Status code : ' . $response->getStatusCode();
    print 'Status message : ' . $response->getStatusMessage();
}

addGeoZone

向特定应用添加一个地理区域。

POST https://api.pushwoosh.com/json/1.3/addGeoZone

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码
geozones	`array`	是	地理区域参数，作为 JSON 数组。
geozones.name	`string`	是	地理区域名称。
geozones.lat	`string`	圆形必需。	地理区域纬度。当设置了 `polygon` 时省略——多边形地理区域会自行推导中心点。
geozones.lng	`string`	圆形必需。	地理区域经度。当设置了 `polygon` 时省略——多边形地理区域会自行推导中心点。
geozones.cooldown	`integer`	是	发送通知后的静默期（以秒为单位）。
geozones.range	`integer`	圆形必需。	地理区域范围（以米为单位）。最小值为 50。当设置了 `polygon` 时省略——多边形地理区域会自行推导其范围。
geozones.polygon	`object`	否	将地理区域设置为多边形而非圆形。不能与 `lat`/`lng`/`range` 组合使用——同时发送两者将被拒绝。请参阅多边形地理区域。
geozones.content	`string or object`	如果 `presetCode` 为空则必需。	地理区域消息内容。
geozones.presetCode	`string`	如果 `content` 为空则必需。	用于替代 `content` 的 Push 预设。
geozones.cluster	`string`	否	指定 `null` 以将集群与地理区域解绑。
geozones.campaign	`string`	否	指定 `null` 以将营销活动与地理区域解绑。如果省略，营销活动值将保持不变。注意：其优先级高于预设中的营销活动。
geozones.timetable	`object`	否	设置时间表间隔。

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // Pushwoosh 应用程序代码
    "geozones": [{
      "name": "Statue of George",            // 必需。地理区域名称。
      "lat": "40.70087797",                   // 必需。地理区域纬度。
      "lng": "-73.931851387",                 // 必需。地理区域经度。
      "cooldown": 60,                         // 以秒为单位，必需。发送通知后的静默期
      "range": 50,                            // 以米为单位，最小 50，必需。地理区域的范围。
      "content": "Lorem ipsum dolor sit amet,
       consectetur adipiscing elit.",         // 或对象
      "presetCode": "AAAAA-BBBBB",            // 可选。可使用 Push 预设代替内容
      "cluster": "GEOZONE CLUSTER CODE",      // 可选。将应用集群的冷却期
      "campaign": "CAMPAIGN_CODE",            // 可选。指定 null 以将营销活动与地理区域解绑
      "timetable": {                          // 可选
        "timezone": 1234,                     // 以秒为单位
        "Mon": [                              // 可用日期：Mon, Tue, Wed, Thu, Fri, Sat, Sun。推送发送
          {
            "start": "04:11",
            "stop": "12:00"
          }
        ],
        "Sun": [
          {                                    // 一个或两个间隔
            "start": "01:11",
            "stop": "17:00"
          },
          {
            "start": "18:01",
            "stop": "23:59"
          }
        ]
      }
    }]
  }
}

一次添加多个地理区域

geozones 接受一个数组，因此一次调用可以创建一整批。在写入任何内容之前，会对整个批次进行验证：如果任何条目被拒绝，则调用失败，并且不会创建该请求中的任何地理区域。错误会通过其在数组中的位置（从零开始计数）来命名违规条目：

{
  "status_code": 210,
  "status_message": "geozones[301]: range: range must be at least 50 meters"
}

修复该条目并再次发送请求。成功后，GeoZones 将按您发送的条目的相同顺序保存新的数字 ID。

大于 500 个条目的批次会被接受并在内部拆分为块。整个数组仍然在第一次写入之前进行验证，但写入本身在块之间不是原子性的：一个条目可以通过验证，但仍然可能写入失败，例如，如果它命名的预设在此期间被删除。在这种情况下，调用返回 200，其中包含已写入的 ID 以及一个 Errors 数组，该数组命名了停止运行的条目，因此创建的任何内容都不会丢失：

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "GeoZones": [100016750, 100016751],
    "Errors": [{ "index": 2, "message": "preset not found" }]
  }
}

当每个条目都已写入时，Errors 不存在，因此完全成功的响应保持不变。GeoZones 数组短于您发送的数组总是意味着某些条目未被创建。

多边形地理区域

发送 polygon 而不是 lat/lng/range 以使地理区域成为多边形。polygon.vertices 是一个有序的 {lat, lng} 点环，描述了形状的轮廓：

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",
    "application": "XXXXX-XXXXX",
    "geozones": [{
      "name": "Downtown mall — ground floor",
      "cooldown": 60,
      "polygon": {
        "vertices": [
          { "lat": 40.70087797, "lng": -73.931851387 },
          { "lat": 40.70112456, "lng": -73.931602211 },
          { "lat": 40.70095321, "lng": -73.930987654 },
          { "lat": 40.70068912, "lng": -73.931233456 }
        ]
      },
      "content": "Welcome! Enjoy 15% off your first purchase today."
    }]
  }
}

lat、lng 和 range 是从环中派生出来的——设备实际监控的圆以形状为中心，半径达到其最远的顶点（最小 50 米）。同时发送 polygon 和 lat/lng/range 将被拒绝。

您可以发送开放或闭合的环——如果最后一个顶点重复第一个顶点，服务器在验证前会删除该闭合的重复项。对结果环的顶点验证：3 到 100 个不同的顶点。如果环的点共线、其边缘自相交或穿过对向子午线，该环也将被拒绝。

updateGeoZone

更新地理区域属性。

POST https://api.pushwoosh.com/json/1.3/updateGeoZone

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
geoZoneId	`string`	是	来自 `/addGeoZone` 请求的地理区域 ID。
name	`string`	否	新的地理区域名称。
cooldown	`integer`	否	要更新的冷却期，以秒为单位。
status	`integer`	否	0 - 停用，1 - 激活。
content	`string`	否	地理区域推送通知的内容。不能与 `presetCode` 一起使用。
cluster	`string`	否	新的集群名称。指定 `null` 以将集群与地理区域解绑。
campaign	`string`	否	新的营销活动 ID。指定 `null` 以将营销活动与地理区域解绑。如果省略，营销活动值将不会更改。其优先级高于预设中的营销活动。
lat	`number`	否	地理区域纬度。不能与 `polygon` 组合使用。
lng	`number`	否	地理区域经度。不能与 `polygon` 组合使用。
range	`integer`	否	新的范围（以米为单位）。不能与 `polygon` 组合使用。
polygon	`object`	否	新的 `{lat, lng}` 顶点环——替换形状并从中重新推导 `lat`/`lng`/`range`。请参阅多边形地理区域。双向有效：在现有圆形地理区域上发送它以将其变为多边形，或在现有地理区域上发送空环 (`{"vertices": []}`) 以将其变回圆形。完全省略 `polygon` 以保持形状不变。顶点验证与 `addGeoZone` 相同。
timetable	`object`	否	地理区域时间表。请参阅下面的更多信息。

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "geoZoneId": 100016750,                  // 必需，来自 /addGeoZone 方法
    "name": "new geozone name",              // 可选
    "cooldown": 222,                         // 以秒为单位，可选
    "status": 0,                             // 可选，0 - 停用，1 - 激活
    "presetCode": "BBBBB-AAAAA",             // 可选，不能与 "content" 一起使用
    "content": "new geozone content",        // 可选，不能与 "presetCode" 一起使用
    "cluster": "GEOZONE CLUSTER CODE",       // 可选。指定 null 以将集群与地理区域解绑
    "campaign": "CAMPAIGN_CODE",             // 可选。指定 null 以将营销活动与地理区域解绑
    "lat": 10.56,                            // 可选，地理区域纬度
    "lng": 12.523,                           // 可选，地理区域经度
    "range": 500,                            // 可选，地理区域范围
    "timetable": {                           // 可选
      "timezone": 1234,                      // 以秒为单位
      "Mon": [                               // 可用日期：Mon, Tue, Wed, Thu, Fri, Sat, Sun。推送发送
        {
          "start": "04:11",
          "stop": "12:00"
        }
      ],
      "Sun": [
        {                                    // 一个或两个间隔
          "start": "01:11",
          "stop": "17:00"
        },
        {
          "start": "18:01",
          "stop": "23:59"
        }
      ]
    }
  }
}

deleteGeoZone

从应用中移除地理区域。

POST https://api.pushwoosh.com/json/1.3/deleteGeoZone

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码
geozones	`string`	是	要移除的地理区域的 ID 数组或单个 ID。

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用程序代码
    "geozones": [550, 526]                   // 必需，地理区域 ID
  }
}

addGeoZoneCluster

向应用添加地理区域集群。

POST https://api.pushwoosh.com/json/1.3/addGeoZoneCluster

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码
name	`string`	是	集群名称。
cooldown	`integer`	是	单个用户可以从地理区域集群接收相同消息之前的延迟时间，以秒为单位。

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用程序代码
    "name": "Raccoon city",                  // 必需，集群名称
    "cooldown": 3210                         // 必需，以秒为单位
  }
}

deleteGeoZoneCluster

从应用中移除地理区域集群。

POST https://api.pushwoosh.com/json/1.3/deleteGeoZoneCluster

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码
geoZoneCluster	`string`	是	要移除的地理区域集群的 ID。

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX",            // 必需，Pushwoosh 应用程序代码
    "geoZoneCluster": "EA1CE-69405"          // 必需，从 /addGeoZoneCluster 请求中获取的集群 ID
  }
}

listGeoZones

检索应用的地理区域列表。

POST https://api.pushwoosh.com/json/1.3/listGeoZones

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX"             // 必需，Pushwoosh 应用程序代码
  }
}

listGeoZoneClusters

检索应用的地理区域集群列表。

POST https://api.pushwoosh.com/json/1.3/listGeoZoneClusters

请求正文参数

参数	类型	必需	描述
auth	`string`	是	来自 Pushwoosh 控制面板的 API 访问令牌。
application	`string`	是	Pushwoosh 应用程序代码

请求示例

{
  "request": {
    "auth": "yxoPUlwqm............pIyEX4H",  // 必需，来自 Pushwoosh 控制面板的 API 访问令牌
    "application": "XXXXX-XXXXX"             // 必需，Pushwoosh 应用程序代码
  }
}