All Products
Document Center

KV storage

Last Updated: May 25, 2021

In many scenarios on the client, key-value storage meets requirements. In most cases, we use NSUserDefaults. However, NSUserDefaults does not support encryption and is slow for data persistence.

In the unified storage component, the key-value storage provides interfaces for storage. PList objects of the NSInteger, long long (the same as NSInteger in 64-bit system), BOOL, double, and NSString types are supported. NSCoding objects are supported. Objective-C objects that can be converted to JSON objects through reflection are also supported. This greatly simplifies object persistence on the client.

For descriptions on most of the interfaces of key-value storage, see the method description in the header file APSharedPreferences.h.

Basic storage types

The unified storage component provides the following types of interfaces for storage:

  1. - (NSInteger)integerForKey:(NSString*)key business:(NSString*)business;
  2. - (NSInteger)integerForKey:(NSString*)key business:(NSString*)business defaultValue:(NSInteger)defaultValue; // Return the default value when the data does not exist.
  3. - (void)setInteger:(NSInteger)value forKey:(NSString*)key business:(NSString*)business;
  4. - (long long)longLongForKey:(NSString*)key business:(NSString*)business;
  5. - (long long)longLongForKey:(NSString*)key business:(NSString*)business defaultValue:(long long)defaultValue; // Return the default value when the data does not exist.
  6. - (void)setLongLong:(long long)value forKey:(NSString*)key business:(NSString*)business;
  7. - (BOOL)boolForKey:(NSString*)key business:(NSString*)business;
  8. - (BOOL)boolForKey:(NSString*)key business:(NSString*)business defaultValue:(BOOL)defaultValue; // Return the default value when the data does not exist.
  9. - (void)setBool:(BOOL)value forKey:(NSString*)key business:(NSString*)business;
  10. - (double)doubleForKey:(NSString*)key business:(NSString*)business;
  11. - (double)doubleForKey:(NSString*)key business:(NSString*)business defaultValue:(double)defaultValue; // Return the default value when the data does not exist.
  12. - (void)setDouble:(double)value forKey:(NSString*)key business:(NSString*)business;

The defaultValue returns the default value when the data does not exist.

Store Objective-C objects

Interface description

The unified storage component provides the following interfaces for storing Objective-C objects:

  1. - (NSString*)stringForKey:(NSString*)key business:(NSString*)business;
  2. - (NSString*)stringForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  3. - (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business;
  4. - (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  5. - (id)objectForKey:(NSString*)key business:(NSString*)business;
  6. - (id)objectForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  7. - (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business;
  8. - (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  9. - (BOOL)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;
  10. - (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business;
  11. - (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  12. - (BOOL)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;
  13. - (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business;
  14. - (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
  15. - (BOOL)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;

setString & stringForKey

When you store NSString objects, setString and stringForKey interfaces is recommended, as the names are more explanatory.

If the data is not encrypted, strings stored by using this interface can be viewed in the SQLite DB viewer. Strings saved in the setObject interface are firstly converted to NSData by using the Property List object and then stored in the database.


When you store Property List objects, we recommend that you use the setObject interface is recommended for it’s highest efficiency.

Property List objects include NSNumber, NSString, NSData, NSDate, NSArray, and NSDictionary objects. The subobjects in NSArray and NSDictionary must also be PList objects.

If you use the setObject interface to store Property List objects, the objects obtained by using the objectForKey interface are mutable. In the following code, the obtained savedArray objects are of the NSMutableArray class.

  1. NSArray* array = [[NSArray alloc] initWithObjects:@"str", nil];
  2. [APCommonPreferences setObject:array forKey:@"array" business:@"biz"];
  3. NSArray* savedArray = [APCommonPreferences objectForKey:@"array" business:@"biz"];


For an Objective-C object that supports the NSCoding protocol, the unified storage component calls the NSKeyedArchiver method in the system to convert the object into an NSData object for persistence.

Property List objects can also use this interface, but with a lower efficiency and thus not recommended.


When an Objective-C object is neither a Property List object nor an NSCoding-supporting one, this method can be utilized for persistence storage.

This method maps the Objective-C object to a JSON string by performing runtime dynamic reflection. However, not all Objective-C objects can be stored in this method. For example, exceptions include Objective-C objects with the C structure pointer, Objective-C objects that are mutually referenced, and Objective-C objects with dictionaries or arrays.


When the unified storage component stores the data of Objective-C objects, it also records the archiving methods. The objects are all obtained in the objectForKey method.

Note: Strings stored in the setString method must be obtained in the stringForKey method.

Data encryption

Using default encryption

Interfaces with extension support encryption and pass in the APDataCrypt structure.

APDefaultEncrypt is the default encryption method. It is AES encryption.

APDefaultDecrypt is the default decryption method. It uses the same key with APDefaultEncrypt.

In most cases, use the default encryption method provided by the unified storage component. The following code shows an example.

  1. [APUserPreferences setObject:aObject forKey:@"key" business:@"biz" extension:APDefaultEncrypt()];
  2. id obj = [APUserPreferences objectForKey:@"key" business:@"biz" extension:APDefaultDecrypt()];
  3. // or
  4. id obj = [APUserPreferences objectForKey:@"key" business:@"biz"];

The default encryption method is used. Therefore, the data acquisition interface can ignore the extension parameter.

Use a custom encryption method

If your business has higher encryption security requirements, you can customize an APDataCrypt structure and specify function pointers for encryption and decryption. But please ensure that the encryption and decryption methods are matched to save and recover data correctly.

Encrypt primary types

To encrypt BOOL, NSInteger, double, and long long objects for storage, you can convert them into strings or put them into the NSNumber class, and then call the setString or setObject interface.

Specify options

  1. typedef NS_OPTIONS (unsigned int, APDataOptions)
  2. {
  3. // Do not use these two options in the interface. They identify the encryption attributes of the data. Use the extension parameter to pass the encryption method.
  4. APDataOptionDefaultEncrypted = 1 << 0, // Do not pass this option, because this option will not be used. The unified storage component uses the extension parameter instead of options in the interface to specify encryption.
  5. APDataOptionCustomEncrypted = 1 << 1, // Do not pass this option, because this option will not be used. The unified storage component uses the extension parameter instead of options in the interface to specify encryption.
  6. // Indicate that the data can be cleared during cache clearance. In this example, unsinged int is used to forcibly transcode 1. For under some compiling options, 1<<31 on the right cannot be calculated by using unsigned int, leading to value assignment failure.
  7. APDataOptionPurgeable = (unsigned int)1 << 31,
  8. };

You can specify options in the setObject, archiveObject, or saveJsonObject method.

APDataOptionPurgeable indicates that the data can be automatically cleared during data clearance. For more information, see Data clearence.