收藏夹概述

收藏夹借助 Telenav 云服务，开发者可以在应用中实现 POI、地址等目的地信息的收藏、分类管理、家/公司地址设置，并支持本地存储与云端同步。

收藏夹功能通常与 Entity Service 搜索模块配合使用：用户通过搜索找到 POI 或地址后，将搜索结果保存为收藏项；应用也可直接管理家、公司、自定义收藏夹等常用目的地。

核心概念

收藏夹管理基于 Marker（标记） 与 Item（收藏项） 两层模型。

Marker（标记）

Marker 表示收藏的分类或标签，即"收藏夹"。分为两类：

类型	说明	示例
系统 Marker	SDK 预定义，无需创建即可使用	`FAVORITE`（收藏）、`HOME`（家）、`WORK`（公司）、`RECENT_STOP`（最近停留）等
用户 Marker	开发者或用户自定义的收藏夹	"常去餐厅"、"周末去处"等

系统 Marker 通过 SystemMarker 枚举定义，常用值包括：

FAVORITE — 通用收藏
HOME — 家地址
WORK — 公司地址
RECENT_STOP — 最近访问地点
NAVIGATED — 曾导航过的地点
SEARCH_HISTORY — 搜索历史

用户 Marker 需先调用 saveMarker 创建，获得 markerId 后再用于收藏。

Item（收藏项）

Item 表示被收藏的具体目的地，通常对应一次搜索得到的 POI 或地址。主要字段如下：

字段	说明
`correlationId`	实体关联 ID，通常来自搜索结果的 Entity ID
`name`	显示名称，如 POI 名称或地址描述
`type`	收藏项类型，POI/地址场景使用 `ENTITY`
`metadata`	扩展信息（JSON 字符串），可存放坐标、地址详情等
`modifiedUtcTimestamp`	最后修改时间戳（UTC 毫秒）

一个 Item 可同时关联多个 Marker。例如同一 POI或者地址既可加入 FAVORITE，也可设为 HOME。

与搜索模块的关系

收藏 POI 或地址的典型流程如下：

搜索（Entity Service）→ 获取实体信息 → 构造 Item → 关联 Marker → 保存/同步（User Service）

用户通过 Entity Service 搜索 POI 或地址，获得实体信息（含 correlationId）。
应用将搜索结果封装为 Item 对象。
调用 markItem，将 Item 关联到目标 Marker（如 FAVORITE、HOME）。
按需调用 sync，将本地变更同步至云端。

说明：correlationId 是连接搜索与收藏的关键字段。请使用搜索 API 返回的实体 ID，以保证收藏项与云端实体数据一致。

主要能力

收藏 POI 与地址 — 将搜索结果加入 FAVORITE 或自定义收藏夹。详见收藏 POI。
设置家/公司地址 — 使用 HOME、WORK 系统 Marker。详见设置家与公司。
查询与管理 — 列表查询、取消收藏、云端同步。详见查询与管理。

API 入口

收藏夹相关 API 通过 UserServiceAPI.getItemMarkAPI() 获取 ItemMarkAPIManager，再调用下列方法：

import com.telenav.user.UserServiceAPI;
import com.telenav.user.api.ItemMarkAPIManager;

ItemMarkAPIManager itemMarkAPI = UserServiceAPI.getItemMarkAPI();

// 示例：查询收藏列表
ListItemsResponse response = itemMarkAPI.listItems()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemType(ItemType.ENTITY)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .execute();

方法	说明
`markItem()`	收藏 POI/地址，将 Item 关联到指定 Marker
`unmarkItem()`	取消单个收藏
`unmarkByMarkers()`	按 Marker 批量取消收藏（可一次清空收藏夹）
`listItems()`	查询收藏项列表
`listMarkers()`	查询 Marker 列表
`saveMarker()`	创建或更新 Marker（含删除）
`markerExists()`	检查用户自定义收藏夹（按名称）是否已存在
`getItemsCount()`	获取指定 Marker 下的收藏项数量
`sync()`	同步 Marker 或 Item 数据至云端

数据流示意

┌─────────────┐     搜索      ┌──────────────────┐
│  用户输入    │ ──────────► │  Entity Service   │
│  POI/地址   │             │  返回 entityId 等  │
└─────────────┘             └────────┬─────────┘
                                     │
                                     ▼ 构造 Item
                            ┌──────────────────┐
                            │   markItem()     │
                            │  关联 Marker     │
                            └────────┬─────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
              ┌──────────┐   ┌──────────┐   ┌──────────────┐
              │ FAVORITE │   │   HOME   │   │ 用户自定义    │
              │  收藏夹   │   │  家地址   │   │   Marker     │
              └──────────┘   └──────────┘   └──────────────┘
                                     │
                                     ▼ sync()
                            ┌──────────────────┐
                            │  Telenav 云服务   │
                            │  多设备数据同步    │
                            └──────────────────┘

前置条件

集成 User Service SDK — 在工程中引入 ums-android AAR 依赖。
初始化 UserServiceManager — 配置 cloudEndPoint 等。
用户登录 — 通过 Identity API 获取 secureToken。
（可选）搜索能力 — 收藏内容来自搜索时，需集成 Entity Service。