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