標籤與別名 API (iOS)
功能說明
溫馨提示，設置標籤別名請注意處理call back結果。
只有call back 返回值爲 0 才設置成功，纔可以向目標推送。否則服務器 API 會返回1011錯誤。所有回調函數都在主線程運行。
提供幾個相關 API 用來設置別名（alias）與標籤（tags）。
這幾個 API 可以在 App 裏任何地方調用。
別名 alias
爲安裝了應用程序的用戶，取個別名來標識。以後給該用戶 Push 消息時，就可以用此別名來指定。
每個用戶只能指定一個別名。
同一個應用程序內，對不同的用戶，建議取不同的別名。這樣，儘可能根據別名來唯一確定用戶。
系統不限定一個別名只能指定一個用戶。如果一個別名被指定到了多個用戶，當給指定這個別名發消息時，服務器端API會同時給這多個用戶發送消息。
舉例：在一個用戶要登錄的遊戲中，可能設置別名爲 userid。遊戲運營時，發現該用戶 3 天沒有玩遊戲了，則根據 userid 調用服務器端API發通知到客戶端提醒用戶。
標籤 tag
爲安裝了應用程序的用戶，打上標籤。其目的主要是方便開發者根據標籤，來批量下發 Push 消息。
可爲每個用戶打多個標籤。
舉例： game, old_page, women
Method - setTagsWithAlias (with Callback)
調用此 API 來同時設置別名與標籤，支持回調函數。
需要理解的是，這個接口是覆蓋邏輯，而不是增量邏輯。即新的調用會覆蓋之前的設置。
在之前調用過後，如果需要再次改變別名與標籤，只需要重新調用此 API 即可。
支持的版本
開始支持的版本：1.4.0
接口定義
+ (void)setTags:(NSSet *)tags alias:(NSString *)alias callbackSelector:(SEL)cbSelector object:(id)theTarget;
參數說明
-
alias
- nil 此次調用不設置此值。
- 空字符串 （@""）表示取消之前的設置。
- 每次調用設置有效的別名，覆蓋之前的設置。
- 有效的別名組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：alias 命名長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
-
tags
- nil 此次調用不設置此值。
- 空集合（[NSSet set]）表示取消之前的設置。
- 集合成員類型要求爲NSString類型
- 每次調用至少設置一個 tag，覆蓋之前的設置，不是新增。
- 有效的標籤組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：每個 tag 命名長度限制爲 40 字節，最多支持設置 100 個 tag，但總長度不得超過1K字節。（判斷長度需採用UTF-8編碼）
- 單個設備最多支持設置 100 個 tag。App 全局 tag 數量無限制。
-
callbackSelector
- nil 此次調用不需要 Callback。
- 用於回調返回對應的參數 alias, tags。並返回對應的狀態碼：0爲成功，其他返回碼請參考錯誤碼定義。
- 回調函數請參考SDK 實現。
-
theTarget
- 參數值爲實現了callbackSelector的實例對象。
- nil 此次調用不需要 Callback。
-(void)tagsAliasCallback:(int)iResCode
tags:(NSSet*)tags
alias:(NSString*)alias
{
NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias);
}
Method - setTagsWithAlias (background)
調用此 API 在後臺同時設置別名與標籤，不需要處理設置結果，SDK會自動進行失敗重試
需要理解的是，這個接口是覆蓋邏輯，而不是增量邏輯。即新的調用會覆蓋之前的設置。
在之前調用過後，如果需要再次改變別名與標籤，只需要重新調用此 API 即可。
需要注意，該background模式的設置和非background的設置是兩種不同的設置，互相不影響，意味着，非background的設置不會終止當前進行的background設置，除非另一個background設置發生。
支持的版本
開始支持的版本：2.1.0
接口定義
+ (void)setTags:(NSSet *)tags aliasInbackground:(NSString *)alias;
參數說明
-
alias
- nil 此次調用不設置此值。
- 空字符串 （@""）表示取消之前的設置。
- 每次調用設置有效的別名，覆蓋之前的設置。
- 有效的別名組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：alias 命名長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
-
tags
- nil 此次調用不設置此值。
- 空集合（[NSSet set]）表示取消之前的設置。
- 集合成員類型要求爲NSString類型
- 每次調用至少設置一個 tag，覆蓋之前的設置，不是新增。
- 有效的標籤組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：每個 tag 命名長度限制爲 40 字節，最多支持設置 100 個 tag，但總長度不得超過1K字節。（判斷長度需採用UTF-8編碼）
- 單個設備最多支持設置 100 個 tag。App 全局 tag 數量無限制。
[JPUSHService setTags:tags aliasInbackground:alias];
Method - setTagsWithAlias (with block)
調用此 API 來同時設置別名與標籤，通過block來返回設置別名與標籤的結果。
需要理解的是，這個接口是覆蓋邏輯，而不是增量邏輯。即新的調用會覆蓋之前的設置。
在之前調用過後，如果需要再次改變別名與標籤，只需要重新調用此 API 即可。
支持的版本
開始支持的版本：2.1.0
接口定義
+ (void)setTags:(NSSet *)tags alias:(NSString *)alias fetchCompletionHandle:(void (^)(int iResCode, NSSet *iTags, NSString *iAlias))completionHandler
參數說明
-
alias
- nil 此次調用不設置此值。
- 空字符串 （@""）表示取消之前的設置。
- 每次調用設置有效的別名，覆蓋之前的設置。
- 有效的別名組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：alias 命名長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
-
tags
- nil 此次調用不設置此值。
- 空集合（[NSSet set]）表示取消之前的設置。
- 集合成員類型要求爲NSString類型
- 每次調用至少設置一個 tag，覆蓋之前的設置，不是新增。
- 有效的標籤組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：每個 tag 命名長度限制爲 40 字節，最多支持設置 100 個 tag，但總長度不得超過1K字節。（判斷長度需採用UTF-8編碼）
- 單個設備最多支持設置 100 個 tag。App 全局 tag 數量無限制。
-
(void (^)(int iResCode, NSSet iTags, NSString iAlias))completionHandler
- completionHandler用於處理設置返回結果
- iResCode返回的結果狀態碼
- iTags和iAlias返回設置的tag和alias
[JPUSHService setTags:tags alias:alias fetchCompletionHandle:^(int iResCode, NSSet *iTags, NSString *iAlias){
NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, iTags, iAlias);
}];
Method - setTags
調用此 API 來設置標籤，支持回調函數。
該方法是 setTagsWithAlias (with Callback) 的簡化版本，用於只變更標籤的情況。
使用建議
如果待設置的 alias / tags 是動態的，有可能在調用 setTagsWithAlias 時因爲 alias / tags 無效而整調用失敗。
調用此方法只設置 tags，可以排除可能的無效的 alias 對本次調用的影響。
支持的版本
開始支持的版本：1.4.0
接口定義
+ (void)setTags:(NSSet *)tags callbackSelector:(SEL)cbSelector object:(id)theTarget;
參數說明
-
tags
- nil 此次調用不設置此值。
- 空集合（[NSSet set]）表示取消之前的設置。
- 每次調用至少設置一個 tag，覆蓋之前的設置，不是新增。
- 有效的標籤組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：每個 tag 命名長度限制爲 40 字節，最多支持設置 100 個tag，但總長度不得超過1K字節。（判斷長度需採用UTF-8編碼）
- 單個設備最多支持設置 100 個 tag。App 全局 tag 數量無限制。
-
callbackSelector
- nil 此次調用不需要 Callback。
- 用於回調返回對應的參數 alias, tags。並返回對應的狀態碼：0爲成功，其他返回碼請參考錯誤碼定義。
- 回調函數請參考SDK 實現。
-
theTarget
-
參數值爲實現了callbackSelector的實例對象。
-
nil 此次調用不需要 Callback。
- (void)tagsAliasCallback:(int)iResCode tags:(NSSet)tags alias:(NSString)alias { NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias);}
Method - setAlias
調用此 API 來設置別名，支持回調函數。
該方法是 setTagsWithAlias (with Callback) 的簡化版本，用於只變更別名的情況。
支持的版本
開始支持的版本：1.4.0
接口定義
+ (void)setAlias:(NSString *)alias callbackSelector:(SEL)cbSelector object:(id)theTarget;
參數說明
- alias
- 空字符串 （@""）表示取消之前的設置。
- 每次調用設置有效的別名，覆蓋之前的設置。
- 有效的別名組成：字母（區分大小寫）、數字、下劃線、漢字。
- 限制：alias 命名長度限制爲 40 字節。（判斷長度需採用UTF-8編碼）
- callbackSelector
- nil 此次調用不需要 Callback。
- 用於回調返回對應的參數 alias, tags。並返回對應的狀態碼：0爲成功，其他返回碼請參考錯誤碼定義。
- 回調函數請參考SDK 實現。
-
theTarget
- 參數值爲實現了callbackSelector的實例對象。
-
nil 此次調用不需要 Callback。
-
(void)tagsAliasCallback:(int)iResCode tags:(NSSet)tags alias:(NSString)alias { NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias) }
Method - filterValidTags
用於過濾出正確可用的 tags。
如果總數量超出最大限制則返回最大數量的靠前的可用tags。
使用建議
設置 tags 時，如果其中一個 tag 無效，則整個設置過程失敗。
如果 App 的 tags 會在運行過程中動態設置，並且存在對 JPush SDK tag 規定的無效字符，則有可能一個 tag 無效導致這次調用裏所有的 tags 更新失敗。
這時你可以調用本方法 filterValidTags 來過濾掉無效的 tags，得到有效的 tags，再調用 JPush SDK 的 set tags / alias 方法。
支持的版本
開始支持的版本：1.4.0
接口定義
+ (NSSet*)filterValidTags:(NSSet*)tags;
參數說明
- tags
- 原 tag 集合。
接口返回
有效的 tag 集合。
錯誤碼定義
| Code | 描述 | 詳細解釋 |
|---|---|---|
| 6001 | 無效的設置，tag/alias 不應參數都爲 null | |
| 6002 | 設置超時 | 建議重試 |
| 6003 | alias 字符串不合法 | 有效的別名、標籤組成：字母（區分大小寫）、數字、下劃線、漢字。 |
| 6004 | alias超長。最多 40個字節 | 中文 UTF-8 是 3 個字節 |
| 6005 | 某一個 tag 字符串不合法 | 有效的別名、標籤組成：字母（區分大小寫）、數字、下劃線、漢字。 |
| 6006 | 某一個 tag 超長。一個 tag 最多 40個字節 | 中文 UTF-8 是 3 個字節 |
| 6007 | tags 數量超出限制。最多 100個 | 這是一臺設備的限制。一個應用全局的標籤數量無限制。 |
| 6008 | tag 超出總長度限制 | 總長度最多 1K 字節 |
| 6011 | 10s內設置tag或alias大於10次 |
短時間內操作過於頻繁 |