Ovatar-iOS Documentation

Ovatar is the quickest and most powerful way to enable avatar support in any client. This documentation focuses on the iOS framework build in Objective C, but can be used in both Objective C and Swift projects. In this documentation, we will show you how to get avatar support in your app in minutes with our super simplified classes that require only a small amount of code. But we also will go into more detail as this framework can give you full control of all Ovatar features. Let's begin…

Registering

To begin using Ovatar in any project you must first obtain a app key. This can be done by first signing up to Ovatar at ovatar.io then creating an app.

NOTE Ovatar is still in BETA so please let us know of any issues, also be aware that some aspects of the framework may change without notice. For this, we suggest using coccopods version control.

Setup

Ovatar can be installed manually by downloading the repo and adding all the & OOvatarIcon header and implementation files.

OR

by adding adding the project though Coccopods (Recommended)

pod 'Ovatar-iOS'

Getting Started

Swift

import OOvatar

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
    OOvatar.sharedInstance(withAppKey: "app_key")
    OOvatar.sharedInstance().setDebugging(true)
    return true
}

Objective C

#import "OOvatar.h"

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[OOvatar sharedInstanceWithAppKey:@"app_key"];
    [[OOvatar sharedInstance] setDebugging:true];
return true;

}

Ovatar Icon (The Easy Way)

To make it quick and easy to get ovatar up and running in your app we designed the OOvatarIcon. This is a powerful class that handles...

downloading images from a key or query (email or phone number)

image caching

automatic image repositioning and sizing

face detection

image selection and uploading with progress

fullscreen previews

image size management

Adding the OvatarIcon

Swift

add the OOvatarIcon framework

import OOvatarIcon

var ovatar: OOvatarIcon?

	ovatar = OOvatarIcon(frame: CGRect(x: (bounds.size.width / 2) - 100.0, y: (bounds.size.height / 2) - 100.0, width: 200.0, height: 200.0))
    ovatar?.placeholder = UIImage(named: "a_custom_placeholder_image")
    ovatar?.oicondelegate = self
    ovatar?.hasaction = true
    ovatar?.preview = false
    ovatar?.allowsphotoediting = true
    ovatar?.onlyfaces = false
    addSubview(headerOvatar)
    ovatar?.imageDownload(withQuery: "user@email.com")

Objective C

.h

add the OOvatarIcon framework

#import "OOvatarIcon/OOvatarIcon.h"

@property (nonatomic, strong) OOvatarIcon *ovatar;

.m

     self.ovatar = [[OOvatarIcon alloc] initWithFrame:CGRectMake((self.bounds.size.width / 2) - 100.0, (self.bounds.size.height / 2) - 100.0, 200.0, 200.0)];
     self.ovatar.placeholder = [UIImage imageNamed:@"a_custom_placeholder_image"];
     self.ovatar.oicondelegate = self;
     self.ovatar.hasaction = true;
     self.ovatar.preview = false;    
     self.ovatar.allowsphotoediting = true;
     self.ovatar.onlyfaces = false;     
     [self addSubview:self.headerOvatar];
          

Let's get that Ovatar!

Querying by Key, Email Address or Phone Number

Ovatar allows you to query of course images uploaded using your app_key can be called with ease (the use of a key) but you can also query Ovatar images by Email Address or Phone Number and all can be achived by calling

Swift

ovatar?.imageDownload(withQuery: "user@email.com")

Objective C

[self.ovatar setOvatarImage:@"user@email.com" phonenumber:@"+4477402847283" fullname:@"Tom Hanks" key:@"[upload_key]" originalImage:@"http://mywebsite.com/user/useravatar.jpeg"];

NOTE In addition to passing a query you can also add a 'name'. This will not query user by name but allow you to store the users name for reference in both the Ovatar Dashboard and for later reference when calling the an image.

NOTE passing an original image URL to originalImage will first migrate this image to ovatar. If you do don't want to migrate images please pass nil

Swift

ovatar?.imageDownload(withQuery:"user@email.com", name:"Rick Sanchez")

Objective C

[self.ovatar imageDownloadWithQuery:@"user@email.com" name:@"Rick Sanchez"];

NOTE If you want to query both a key and a email address as fall back simply add this method multiple times.

Swift

		ovatar?.imageDownload(withQuery: "user@email.com") //email address query
        ovatar?.imageDownload(withQuery: "+44000000000000")//uk phone number query
        ovatar?.imageDownload(withQuery: "my_uploaded_ovatar_key")//query by key
	

Objective C

		
		[self.ovatar imageDownloadWithQuery:@"user@email.com"];  //email address query
		[self.ovatar imageDownloadWithQuery:@"+44000000000000"];  //uk phone number query
		[self.ovatar imageDownloadWithQuery:@"my_uploaded_ovatar_key"]; //query by key
	

By default the class will load the images by key. If no image can be found via key it will fallback to any queryies.

NOTE Some users have reported this not working, this is because they called this before the OOvatarIcon was initialized. Please make sure you add OOvatarIcon to your project first!

Setting your own icon

In some cases you may have an avatar icon from another service you would like to use. To do so you can just call

Swift

ovatar?.imageSet(UIImage(named: "my_local_image.png"), animated: true)

Objective C

[self.ovatar imageSet:[UIImage imageNamed:@"my_local_image.png"] animated:TRUE]

Manual Uploading

We advise using the power of the OOvatarIcon class for selecting, managing and uploading new images but if you do wish to upload an image manually you can do so by calling.

Swift

 let imagedata = .uiImageJPEGRepresentation() as? Data
 let metadata = ["copyright": "joe barbour"]
 ovatar?.imageUpdate(withImage: imagedata, info: nil)	

Objective C

NSData *imagedata = UIImageJPEGRepresentation([UIImage imageNamed:@"my_selected_image.jpg"], 0.8);
NSDictionary *metadata = @{@"copyright":@"joe barbour"};
[self.ovatar imageUpdateWithImage:imagedata info:nil];

NOTE Metadata is returned by querying the JSON output, this by directly calling the OOvatar class. See more below.

The Power of the OOvatarIcon

Placeholder

A placeholder image can be set be set if there is no image available. This can be done by setting the placeholder as a UIImage. If this is not set the default ovatar placeholder will be set, but this done via a remote image request. We recommend setting your own placeholder to match your UI to avoid any empty states.

Editing

there will be occasions in your app where you will want to allow the user to edit/change their avatar and there will be times where you don't. By default, the user will not be able to interact with an image. But you can change this by setting the hasaction = true;. When set to TRUE, tapping on the OOvatarIcon will either call the ovatarIconWasTappedWithGesture delegate method (see more about delegate callbacks below) or launch the default iOS Gallery Picker right from the subview. By default, the Gallery Picker will be presented, but this can be disabled by setting presentpicker = false;

Only Faces

Let's say you're building a dating app? Then you won't want your users to have photos of their dog or their holiday, you want accurate photos of that person. By setting onlyfaces = true; the class will quickly detect if the selected image indeed has a human face within. If it does then the image will be uploaded but if the user selects an image without a face then the ovatarIconUploadFailedWithErrors will be called with an NSError. (see below for more information about delegate callbacks)

Image Editing

Images sizes are managed by Ovatar directly but cropping is not (currently). To make this easy you can set allowsphotoediting = true; and when the user selects an image from the default iOS Gallery Picker they will be presented with the default iOS cropping tool. Here the user can resize and reposition the image as they see fit. By default this is disabled.

Animation

OOvatarIcon uses low level animations such as crossfades for when new images are loaded and scale 'bounces' when the icon is tapped. All these animations can be disabled by calling animated = false;

Additionally, for more control you can change the crossfade duration by setting crossfade = 1.0;. By deafult this is 0.6.

Full Preview

Sometimes ovatar images maybe just there as a reference point and maybe to small to see. Enabling preview means when the user taps on an image they will be able to see the Ovatar in full screen. Here a higher resolution will be automatically loaded. This can be enabled on any OOvatarIcon that is not editable (hasaction = true;). By default this is disabled, but can be enabled by preview = true;

Additionally, you can set a custom caption in the full-screen view. This could be information about the user or just about anything. To add this setting previewcaption = "This is my Ovatar Caption"

Loader

When an Ovatar is downloading or uploading a progress spinner/bar will be presented over the OvatarIcon. By default this is enabled but can be disabled by progressloader = false;

Delegate Callbacks

For more precice control the OvatarIcon has 4 delegate callbacks. To enable these you must declare the OOvatarIcon as a delegate by oicondelegate = self;

Swift

func ovatarIconWasTapped(withGesture gesture: UITapGestureRecognizer?) {
    //Called if the 'presentpicker' BOOL is set to FALSE (by default it is set to TRUE). Here you can set custom actions for the when the Ovatar Icon is tapped.
}

func ovatarIconWasUpdatedSucsessfully(_ output: [AnyHashable: Any]?) {
    //Called if an image is uploaded successfully.
}

func ovatarIconUploadFailed() throws {
    //Called if an image cannot be uploaded, see the documentation for error codes.
}

func ovatarIconUploading(withProgress progress: Float) {
    //Called everytime the progress of the upload changes. The progress with displayed as in double value on a 0-100 scale.
}

Objective C

-(void)ovatarIconWasTappedWithGesture:(UITapGestureRecognizer *)gesture {
    //Called if the 'presentpicker' BOOL is set to FALSE (by default it is set to TRUE). Here you can set custom actions for the when the Ovatar Icon is tapped.
}   

-(void)ovatarIconWasUpdatedSucsessfully:(NSDictionary *)output {
    //Called if an image is uploaded successfully.
}

-(void)ovatarIconUploadFailedWithErrors:(NSError *)error {
    //Called if an image cannot be uploaded, see the documentation for error codes.
}

-(void)ovatarIconUploadingWithProgress:(float)progress {
    //Called everytime the progress of the upload changes. The progress with displayed as in double value on a 0-100 scale.
}

Debugging & Options

The following can be set from anywhere in your app but we recommend setting the following variables in the didFinishLaunchingWithOptions method in your

Name

store the users fullname when uploading an ovatar

Swift

OOvatar.sharedInstance().setName("Steve Jobs")

Objective C

[[OOvatar sharedInstance] setName:@"Steve Jobs"];

Debugging

to enable console debugging simply set

Swift

OOvatar.sharedInstance().setDebugging(true)

Objective C

[[OOvatar sharedInstance] setDebugging:true];

Gravatar Support

by default if an avatar cannot be found Ovatar will attempt to fallback on Gravatar. This can be disabled.

Swift

OOvatar.sharedInstance().setGravatarFallback(false)

Objective C

[[OOvatar sharedInstance] setGravatarFallback:false];

Caching

When an ovatar image is initially downloaded it is saved ti the local cache. This it to prevent unnecessary server calls. The caching cannot be disabled but the expiry can be changed by setting

Swift

OOvatar.sharedInstance().setCacheExpirySeconds(60 * 60 * 4)//in seconds

Objective C

[[OOvatar sharedInstance] setCacheExpirySeconds:60*60*4];//in seconds