收藏 POI 与地址

本文介绍如何将搜索得到的 POI、地址收藏到用户收藏夹，以及如何创建自定义收藏夹。

前置阅读：概述、搜索概述、用户账号

基本介绍

收藏 POI 或地址时，应用需要完成两件事：

将搜索返回的实体信息封装为 Item（收藏项）。
调用 markItem，把 Item 关联到目标 Marker（收藏夹）。

默认收藏夹使用系统 Marker FAVORITE，无需事先创建。若需自定义收藏夹（如"常去餐厅"），需先调用 saveMarker 创建用户 Marker。

核心模型

Item（收藏项）

字段	说明	是否必填
`correlationId`	搜索返回的实体 ID	是
`name`	显示名称（POI 名或地址描述）	是
`type`	收藏项类型，POI/地址使用 `ENTITY`	是
`metadata`	扩展信息 JSON（坐标、地址详情等）	否
`modifiedUtcTimestamp`	最后修改时间（UTC 毫秒）	是
`itemId`	收藏项 ID，新建时无需设置；更新或取消收藏时使用	否

Marker（收藏夹）

类型	说明
`FAVORITE`	系统默认收藏夹，直接使用，无需创建
用户自定义 Marker	通过 `saveMarker` 创建，如"周末去处"

收藏流程

搜索（Entity Service）→ 获取 entityId → 构造 Item → markItem(FAVORITE) → （可选）sync

用户通过 Entity Service 搜索找到 POI 或地址。
从搜索结果中取出 entityId，作为 Item.correlationId。
调用 markItem，将 Item 关联到 SystemMarker.FAVORITE。
设置 setNeedSync(true) 时，变更会同步至云端。

API 说明

markItem — 收藏 POI/地址

方法	说明
`setItem(Item item)`	收藏项，含 `correlationId`、`name`、`type` 等
`setMarkerId(String markerId)`	目标 Marker ID，默认收藏为 `FAVORITE`
`setMarkerType(MarkerType markerType)`	`SYSTEM` 或 `USER`
`setSecureToken(String token)`	登录后获得的会话令牌
`setApplicationId(String id)`	应用 API Key
`setApplicationSignature(String sig)`	应用签名
`setNeedSync(boolean needSync)`	是否立即同步至云端

返回值：MarkResponse，其中 getMarkedItem().getItemId() 为收藏项 ID，后续更新或取消收藏时使用。

更新已有收藏项时，在 Item 中设置 itemId（来自 markItem 或 listItems 返回值），并更新 name、metadata、modifiedUtcTimestamp 等字段后再次调用 markItem。取消收藏请使用 unmarkItem，参见下方示例及查询与管理。

saveMarker — 创建自定义收藏夹

方法	说明
`setMarker(Marker marker)`	Marker 对象，设置 `label`、`markerType`
`setSecureToken(String token)`	会话令牌

返回值：SaveMarkerResponse，其中 getSavedMarker().getMarkerId() 为新建收藏夹 ID。

删除自定义收藏夹：推荐使用 unmarkByMarkers 并设置 deleteMarker=true（同时清空收藏并删除收藏夹）。亦可对同一 Marker 调用 saveMarker 并设置 marker.setDeleted(true)，但该方式不会自动解除已同步 Marker 下的 Item 关联。详见批量清空收藏。

代码示例

收藏搜索结果中的 POI

import com.telenav.user.UserServiceAPI;
import com.telenav.user.vo.*;

// 1. 构造收藏项（数据来自搜索结果）
Item item = new Item();
item.setCorrelationId(searchResult.getEntityId());   // 搜索返回的实体 ID
item.setName(searchResult.getName());
item.setType(ItemType.ENTITY);
item.setMetadata(searchResult.getMetadata());        // 可选
item.setModifiedUtcTimestamp(System.currentTimeMillis());

// 2. 收藏到默认收藏夹 FAVORITE
MarkResponse response = UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

String itemId = response.getMarkedItem().getItemId();

创建自定义收藏夹并收藏

// 1. 创建自定义 Marker
Marker userMarker = new Marker();
userMarker.setLabel("常去餐厅");
userMarker.setMarkerType(MarkerType.USER);
userMarker.setDeleted(false);

SaveMarkerResponse saveResponse = UserServiceAPI.getItemMarkAPI()
    .saveMarker()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(userMarker)
    .execute();

String markerId = saveResponse.getSavedMarker().getMarkerId();

// 2. 将 POI 收藏到该 Marker
MarkResponse markResponse = UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(markerId)
    .setMarkerType(MarkerType.USER)
    .setNeedSync(true)
    .execute();

更新收藏项

对已存在的 Item 修改 name、metadata 等字段时，需传入 itemId，再调用 markItem：

// 从 listItems 或 markItem 返回值获取 itemId
String itemId = existingItem.getItemId();

Item item = new Item();
item.setItemId(itemId);                              // 标识已有收藏项
item.setCorrelationId(existingItem.getCorrelationId());
item.setName("更新后的名称");
item.setType(ItemType.ENTITY);
item.setMetadata(updatedMetadata);
item.setModifiedUtcTimestamp(System.currentTimeMillis());

MarkResponse response = UserServiceAPI.getItemMarkAPI()
    .markItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItem(item)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

若未设置 itemId，但 correlationId 与 type 能匹配到唯一已有 Item，SDK 也会执行更新而非新建。

取消收藏

Item 没有类似 Marker 的 setDeleted(true)。取消收藏需调用 unmarkItem，取消 Item 与指定 Marker 的关联：

UnmarkResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemId(itemId)                                // markItem 或 listItems 返回的 itemId
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

从自定义收藏夹移除时，将 markerId / markerType 替换为对应的用户 Marker：

    .setMarkerId(customMarkerId)
    .setMarkerType(MarkerType.USER)

unmarkItem 仅取消 Item 与 Marker 的关联。若 Item 不再关联任何 Marker，是否从本地消失取决于同步状态，详见查询与管理。

批量清空收藏

推荐使用 unmarkByMarkers 按 Marker 一次性取消该收藏夹下的全部关联，无需 listItems + 循环 unmarkItem。详见查询与管理。

// 清空 FAVORITE 下的全部收藏（保留收藏夹本身）
UnmarkByMarkersResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkByMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(SystemMarker.FAVORITE.name(), MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

int cleared = response.getTotalClearedCount();

// 清空并删除用户自定义收藏夹「常去餐厅」
UnmarkByMarkersResponse deleteResponse = UserServiceAPI.getItemMarkAPI()
    .unmarkByMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(customMarkerId, MarkerType.USER, true)   // 第三个参数 deleteMarker=true
    .setNeedSync(true)
    .execute();

boolean markerDeleted = deleteResponse.getResults().get(0).isMarkerDeleted();

说明：

系统 Marker（FAVORITE 等）不可设置 deleteMarker=true，仅取消 Item 关联。

setNeedSync(true) 会同步 Item；用户 Marker 且 deleteMarker=true 时，还会同步 Marker。

若 Item 还关联其他 Marker，取消后仍会保留在那些收藏夹中。

注意事项

correlationId 必须使用搜索 API 返回的实体 ID，不要自行构造，以保证与云端实体数据一致。
同一 POI 可收藏到多个 Marker，例如同时加入 FAVORITE 和自定义收藏夹，需分别调用 markItem。
metadata 建议存放坐标、完整地址等，便于离线展示；JSON 结构由应用自行定义。
离线时数据写入本地，网络恢复后调用 sync 同步。