Няма описание

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312
  1. /*
  2. * Copyright 2019 Google
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License");
  5. * you may not use this file except in compliance with the License.
  6. * You may obtain a copy of the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS,
  12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. * See the License for the specific language governing permissions and
  14. * limitations under the License.
  15. */
  16. #import <Foundation/Foundation.h>
  17. NS_ASSUME_NONNULL_BEGIN
  18. @class FIRInstanceIDResult;
  19. /**
  20. * @memberof FIRInstanceID
  21. *
  22. * The scope to be used when fetching/deleting a token for Firebase Messaging.
  23. */
  24. FOUNDATION_EXPORT NSString *const kFIRInstanceIDScopeFirebaseMessaging
  25. NS_SWIFT_NAME(InstanceIDScopeFirebaseMessaging);
  26. #if defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
  27. /**
  28. * Called when the system determines that tokens need to be refreshed.
  29. * This method is also called if Instance ID has been reset in which
  30. * case, tokens and FCM topic subscriptions also need to be refreshed.
  31. *
  32. * Instance ID service will throttle the refresh event across all devices
  33. * to control the rate of token updates on application servers.
  34. */
  35. FOUNDATION_EXPORT const NSNotificationName kFIRInstanceIDTokenRefreshNotification
  36. NS_SWIFT_NAME(InstanceIDTokenRefresh);
  37. #else
  38. /**
  39. * Called when the system determines that tokens need to be refreshed.
  40. * This method is also called if Instance ID has been reset in which
  41. * case, tokens and FCM topic subscriptions also need to be refreshed.
  42. *
  43. * Instance ID service will throttle the refresh event across all devices
  44. * to control the rate of token updates on application servers.
  45. */
  46. FOUNDATION_EXPORT NSString *const kFIRInstanceIDTokenRefreshNotification
  47. NS_SWIFT_NAME(InstanceIDTokenRefreshNotification);
  48. #endif // defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
  49. /**
  50. * @related FIRInstanceID
  51. *
  52. * The completion handler invoked when the InstanceID token returns. If
  53. * the call fails we return the appropriate `error code` as described below.
  54. *
  55. * @param token The valid token as returned by InstanceID backend.
  56. *
  57. * @param error The error describing why generating a new token
  58. * failed. See the error codes below for a more detailed
  59. * description.
  60. */
  61. typedef void (^FIRInstanceIDTokenHandler)(NSString *__nullable token, NSError *__nullable error)
  62. NS_SWIFT_NAME(InstanceIDTokenHandler);
  63. /**
  64. * @related FIRInstanceID
  65. *
  66. * The completion handler invoked when the InstanceID `deleteToken` returns. If
  67. * the call fails we return the appropriate `error code` as described below
  68. *
  69. * @param error The error describing why deleting the token failed.
  70. * See the error codes below for a more detailed description.
  71. */
  72. typedef void (^FIRInstanceIDDeleteTokenHandler)(NSError *error)
  73. NS_SWIFT_NAME(InstanceIDDeleteTokenHandler);
  74. /**
  75. * @related FIRInstanceID
  76. *
  77. * The completion handler invoked when the app identity is created. If the
  78. * identity wasn't created for some reason we return the appropriate error code.
  79. *
  80. * @param identity A valid identity for the app instance, nil if there was an error
  81. * while creating an identity.
  82. * @param error The error if fetching the identity fails else nil.
  83. */
  84. typedef void (^FIRInstanceIDHandler)(NSString *__nullable identity, NSError *__nullable error)
  85. NS_SWIFT_NAME(InstanceIDHandler);
  86. /**
  87. * @related FIRInstanceID
  88. *
  89. * The completion handler invoked when the app identity and all the tokens associated
  90. * with it are deleted. Returns a valid error object in case of failure else nil.
  91. *
  92. * @param error The error if deleting the identity and all the tokens associated with
  93. * it fails else nil.
  94. */
  95. typedef void (^FIRInstanceIDDeleteHandler)(NSError *__nullable error)
  96. NS_SWIFT_NAME(InstanceIDDeleteHandler);
  97. /**
  98. * @related FIRInstanceID
  99. *
  100. * The completion handler invoked when the app identity and token are fetched. If the
  101. * identity wasn't created for some reason we return the appropriate error code.
  102. *
  103. * @param result The result containing an identity for the app instance and a valid token,
  104. * nil if there was an error while creating the result.
  105. * @param error The error if fetching the identity or token fails else nil.
  106. */
  107. typedef void (^FIRInstanceIDResultHandler)(FIRInstanceIDResult *__nullable result,
  108. NSError *__nullable error)
  109. NS_SWIFT_NAME(InstanceIDResultHandler);
  110. /**
  111. * Public errors produced by InstanceID.
  112. */
  113. typedef NS_ENUM(NSUInteger, FIRInstanceIDError) {
  114. // Http related errors.
  115. /// Unknown error.
  116. FIRInstanceIDErrorUnknown = 0,
  117. /// Auth Error -- GCM couldn't validate request from this client.
  118. FIRInstanceIDErrorAuthentication = 1,
  119. /// NoAccess -- InstanceID service cannot be accessed.
  120. FIRInstanceIDErrorNoAccess = 2,
  121. /// Timeout -- Request to InstanceID backend timed out.
  122. FIRInstanceIDErrorTimeout = 3,
  123. /// Network -- No network available to reach the servers.
  124. FIRInstanceIDErrorNetwork = 4,
  125. /// OperationInProgress -- Another similar operation in progress,
  126. /// bailing this one.
  127. FIRInstanceIDErrorOperationInProgress = 5,
  128. /// InvalidRequest -- Some parameters of the request were invalid.
  129. FIRInstanceIDErrorInvalidRequest = 7,
  130. } NS_SWIFT_NAME(InstanceIDError);
  131. /**
  132. * A class contains the results of InstanceID and token query.
  133. */
  134. NS_SWIFT_NAME(InstanceIDResult)
  135. @interface FIRInstanceIDResult : NSObject <NSCopying>
  136. /**
  137. * An instanceID uniquely identifies the app instance.
  138. */
  139. @property(nonatomic, readonly, copy) NSString *instanceID;
  140. /*
  141. * Returns a Firebase Messaging scoped token for the firebase app.
  142. */
  143. @property(nonatomic, readonly, copy) NSString *token;
  144. @end
  145. /**
  146. * Instance ID provides a unique identifier for each app instance and a mechanism
  147. * to authenticate and authorize actions (for example, sending an FCM message).
  148. *
  149. * Once an InstanceID is generated, the library periodically sends information about the
  150. * application and the device where it's running to the Firebase backend. To stop this. see
  151. * `[FIRInstanceID deleteIDWithHandler:]`.
  152. *
  153. * Instance ID is long lived but, may be reset if the device is not used for
  154. * a long time or the Instance ID service detects a problem.
  155. * If Instance ID is reset, the app will be notified via
  156. * `kFIRInstanceIDTokenRefreshNotification`.
  157. *
  158. * If the Instance ID has become invalid, the app can request a new one and
  159. * send it to the app server.
  160. * To prove ownership of Instance ID and to allow servers to access data or
  161. * services associated with the app, call
  162. * `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`.
  163. */
  164. NS_SWIFT_NAME(InstanceID)
  165. @interface FIRInstanceID : NSObject
  166. /**
  167. * FIRInstanceID.
  168. *
  169. * @return A shared instance of FIRInstanceID.
  170. */
  171. + (instancetype)instanceID NS_SWIFT_NAME(instanceID());
  172. /**
  173. * Unavailable. Use +instanceID instead.
  174. */
  175. - (instancetype)init __attribute__((unavailable("Use +instanceID instead.")));
  176. #pragma mark - Tokens
  177. /**
  178. * Returns a result of app instance identifier InstanceID and a Firebase Messaging scoped token.
  179. * param handler The callback handler invoked when an app instanceID and a default token
  180. * are generated and returned. If instanceID and token fetching fail for some
  181. * reason the callback is invoked with nil `result` and the appropriate error.
  182. */
  183. - (void)instanceIDWithHandler:(FIRInstanceIDResultHandler)handler;
  184. /**
  185. * Returns a token that authorizes an Entity (example: cloud service) to perform
  186. * an action on behalf of the application identified by Instance ID.
  187. *
  188. * This is similar to an OAuth2 token except, it applies to the
  189. * application instance instead of a user.
  190. *
  191. * This is an asynchronous call. If the token fetching fails for some reason
  192. * we invoke the completion callback with nil `token` and the appropriate
  193. * error.
  194. *
  195. * This generates an Instance ID if it does not exist yet, which starts periodically sending
  196. * information to the Firebase backend (see `[FIRInstanceID getIDWithHandler:]`).
  197. *
  198. * Note, you can only have one `token` or `deleteToken` call for a given
  199. * authorizedEntity and scope at any point of time. Making another such call with the
  200. * same authorizedEntity and scope before the last one finishes will result in an
  201. * error with code `OperationInProgress`.
  202. *
  203. * @see FIRInstanceID deleteTokenWithAuthorizedEntity:scope:handler:
  204. *
  205. * @param authorizedEntity Entity authorized by the token.
  206. * @param scope Action authorized for authorizedEntity.
  207. * @param options The extra options to be sent with your token request. The
  208. * value for the `apns_token` should be the NSData object
  209. * passed to the UIApplicationDelegate's
  210. * `didRegisterForRemoteNotificationsWithDeviceToken` method.
  211. * The value for `apns_sandbox` should be a boolean (or an
  212. * NSNumber representing a BOOL in Objective-C) set to true if
  213. * your app is a debug build, which means that the APNs
  214. * device token is for the sandbox environment. It should be
  215. * set to false otherwise. If the `apns_sandbox` key is not
  216. * provided, an automatically-detected value shall be used.
  217. * @param handler The callback handler which is invoked when the token is
  218. * successfully fetched. In case of success a valid `token` and
  219. * `nil` error are returned. In case of any error the `token`
  220. * is nil and a valid `error` is returned. The valid error
  221. * codes have been documented above.
  222. */
  223. - (void)tokenWithAuthorizedEntity:(NSString *)authorizedEntity
  224. scope:(NSString *)scope
  225. options:(nullable NSDictionary *)options
  226. handler:(FIRInstanceIDTokenHandler)handler;
  227. /**
  228. * Revokes access to a scope (action) for an entity previously
  229. * authorized by `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`.
  230. *
  231. * This is an asynchronous call. Call this on the main thread since InstanceID lib
  232. * is not thread safe. In case token deletion fails for some reason we invoke the
  233. * `handler` callback passed in with the appropriate error code.
  234. *
  235. * Note, you can only have one `token` or `deleteToken` call for a given
  236. * authorizedEntity and scope at a point of time. Making another such call with the
  237. * same authorizedEntity and scope before the last one finishes will result in an error
  238. * with code `OperationInProgress`.
  239. *
  240. * @param authorizedEntity Entity that must no longer have access.
  241. * @param scope Action that entity is no longer authorized to perform.
  242. * @param handler The handler that is invoked once the unsubscribe call ends.
  243. * In case of error an appropriate error object is returned
  244. * else error is nil.
  245. */
  246. - (void)deleteTokenWithAuthorizedEntity:(NSString *)authorizedEntity
  247. scope:(NSString *)scope
  248. handler:(FIRInstanceIDDeleteTokenHandler)handler;
  249. #pragma mark - Identity
  250. /**
  251. * Asynchronously fetch a stable identifier that uniquely identifies the app
  252. * instance. If the identifier has been revoked or has expired, this method will
  253. * return a new identifier.
  254. *
  255. * Once an InstanceID is generated, the library periodically sends information about the
  256. * application and the device where it's running to the Firebase backend. To stop this. see
  257. * `[FIRInstanceID deleteIDWithHandler:]`.
  258. *
  259. * @param handler The handler to invoke once the identifier has been fetched.
  260. * In case of error an appropriate error object is returned else
  261. * a valid identifier is returned and a valid identifier for the
  262. * application instance.
  263. */
  264. - (void)getIDWithHandler:(FIRInstanceIDHandler)handler NS_SWIFT_NAME(getID(handler:));
  265. /**
  266. * Resets Instance ID and revokes all tokens.
  267. *
  268. * This method also triggers a request to fetch a new Instance ID and Firebase Messaging scope
  269. * token. Please listen to kFIRInstanceIDTokenRefreshNotification when the new ID and token are
  270. * ready.
  271. *
  272. * This stops the periodic sending of data to the Firebase backend that began when the Instance ID
  273. * was generated. No more data is sent until another library calls Instance ID internally again
  274. * (like FCM, RemoteConfig or Analytics) or user explicitly calls Instance ID APIs to get an
  275. * Instance ID and token again.
  276. */
  277. - (void)deleteIDWithHandler:(FIRInstanceIDDeleteHandler)handler NS_SWIFT_NAME(deleteID(handler:));
  278. @end
  279. NS_ASSUME_NONNULL_END