標籤與別名 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 集合。

錯誤碼定義