BatchUserDataEditor

@interface BatchUserDataEditor : NSObject

/**
 Override the detected user language.
 
 @param language Language override: lowercase, ISO 639 formatted string. nil to reset.
 */
- (void)setLanguage:(nullable NSString*)language;

/**
 Override the detected user region.
 
 @param region Region override: uppercase, ISO 3166 formatted string. nil to reset.
 */
- (void)setRegion:(nullable NSString*)region;

/**
 Set the user identifier.
 
 @warning Be careful: you should make sure the identifier uniquely identifies a user. When pushing an identifier, all installations with that identifier will get the Push, which can cause some privacy issues if done wrong.
 
 @param identifier User identifier.
 */
- (void)setIdentifier:(nullable NSString*)identifier;

/**
 Set a custom user attribute for a key.
 
 The attribute can be one of the following types, or their native Swift equivalent
 
 - NSString
 
    Must not be longer than 64 characters. Can be empty.
    For better results, you should make them upper/lowercase and trim the whitespaces.
 
 - NSNumber
 
    Anything bigger than a `long long` or a `double` will be rejected.
    Unsigned values will be rejected.
    Booleans are supported, but should be initialized with `[NSNumber numberWithBool:<your value>]` or `@YES/@NO`.
 
 - NSDate
 
    Note that since timezones are not supported, this will typically represent UTC dates.
    Using any unsupported type as a value (NSNull, NSObject, NSArray, NSDictionary for example) will **NOT** work.
 
 - NSURL
 
     Must not be longer than 2048 characters. Can't be empty.
     Must follow the format 'scheme://[authority][path][?query][#fragment]'.
 
 @param attribute The attribute value. If nil, the attribute will be removed. See method description for more info about what's allowed.
 
 @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
 */
- (void)setAttribute:(nullable NSObject*)attribute forKey:(nonnull NSString*)key;

/// Set a boolean custom user attribute for a key.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setBooleanAttribute:(BOOL)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set a date custom user attribute for a key.
/// Note that since timezones are not supported, this will typically represent UTC dates.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setDateAttribute:(nonnull NSDate*)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set a string custom user attribute for a key.
/// Must not be longer than 64 characters. Can be empty.
/// For better results, you should make them upper/lowercase and trim the whitespaces.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setStringAttribute:(nonnull NSString*)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set a boolean custom user attribute for a key.
/// Anything bigger than a `long long` or a `double` will be rejected.
/// Unsigned values will be rejected.
/// Booleans are supported, but should be initialized with `[NSNumber numberWithBool:<your value>]` or `@YES/@NO`.
/// Note: `setBoolean/Integer/LongLong/Float/Double` should be preferred over this method, especially for booleans.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setNumberAttribute:(nonnull NSNumber*)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set an NSInteger/Int custom user attribute for a key.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setIntegerAttribute:(NSInteger)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set an long long/Int64 custom user attribute for a key.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setLongLongAttribute:(long long)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set an float custom user attribute for a key.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setFloatAttribute:(float)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set an double custom user attribute for a key.
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setDoubleAttribute:(double)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/// Set an url custom user attribute for a key.
/// Must not be longer than 2048 characters. Can't be empty or nil.
/// Must follow the format 'scheme://[authority][path][?query][#fragment]'
/// @param attribute The attribute value.
/// @param key The attribute key. Can't be nil. It should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
/// @param error Pointer to an error describing. Note that the error is only about key/value validation, and doesn't mean the value has been sent to the server yet.
/// @returns A boolean indicating whether the attribute passed validation or not.
- (BOOL)setURLAttribute:(nonnull NSURL*)attribute forKey:(nonnull NSString*)key error:(NSError * _Nullable * _Nullable)error NS_SWIFT_NAME(set(attribute:forKey:));

/**
 Removes an attribute for the specified key.
 
 @param key The attribute key. Can't be nil.
 */
- (void)removeAttributeForKey:(nonnull NSString*)key;

/**
 Removes all custom attributes.
 
 @warning Once saved, this action cannot be undone.
 */
- (void)clearAttributes;

/**
 Add a tag to the specified collection. If empty, the collection will be created automatically.
 
 @param tag The tag to add. Cannot be nil or empty. Must be a string no longer than 64 characters.
 
 @param collection The tag collection name. Cannot be nil. Must be a string of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
 */
- (void)addTag:(nonnull NSString*)tag inCollection:(nonnull NSString*)collection;

/**
 Removes a tag from the specified collection.
 
 @param tag The tag to remove. Cannot be nil. If the tag doesn't exist, this method will do nothing.
 
 @param collection The tag collection name. Cannot be nil. Must be a string of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters. If the collection doesn't exist, this method will do nothing, but apply won't fail.
 */
- (void)removeTag:(nonnull NSString*)tag fromCollection:(nonnull NSString*)collection;

/**
 Removes all tags.
 
 @warning Once saved, this action cannot be undone.
 */
- (void)clearTags;

/**
 Removes all tags from a collection.
 
 @warning Once applied, this action cannot be undone.
 
 @param collection The tag collection name. Cannot be nil. Must be a string of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
 */
- (void)clearTagCollection:(nonnull NSString*)collection;

/**
 Save all of the pending changes made in that editor.
 
 @warning This action cannot be undone.
 */
- (void)save;

@end