IntroductionReveal

Ovatar.io is the simplest way for developers to integrate avatar support into their apps and websites. Ovatar handles the uploading, storing, resizing and framing avatars along with handling and parsing of metadata and facial data points (such as age) along with many many other features.

Our powerful REST API that can be integrated into any project or platform with ease, but we have also build out custom libraries for iOS and Android to make it even easier to get avatars into your app.

PrivacyReveal

There is not much more personal than a photo of a person, with this privacy is super important to us. With this ovatar puts the user first by giving them full control over their data. To achieve this we give control to you (the app owner) as well as to the user directly.

App Owner

the app owner (you or your team) has the ability to revoke or append any image uploaded by your application at any time with the 'ovatar' endpoint. Any custom integration of ovatar that does not allow the user to do this in their app will violate our terms of service and will have their application terminated.

User

the user will be notified of any uploaded photo of themselves via an email delivered to them. They will be able to append or revoke this upload at any time using the ovatar.io dashboard. In some cases, you may wish to update your own data when changes have been made by the user which is why we have webhook support.

ReferenceReveal

All Ovatar.io endpoints return by default a JSON object. This structure varies depending on the endpoint, but all calls DO return a error_code [integer] and a status [string] along with a HTTP Status Code.

Example JSON Response

[{
    "status": "image not found",
    "error_code": 422
}]

Ovatar.io uses HTTPS by default, all requests should be made using the base url below

https://ovatar.io/api/

AuthenticationReveal

Currently, the endpoints available do not require any user authentication, this is subject to change in future versions.

But for each request, an AppKey is required. This app key will be used to identify who uploaded what and gives developers a sense of responsibility. Additionally, the AppKey will also be used to monitor and limit your requests, based on your chosen plan

To obtain an application key please register your interest here.

The app key should be passed in an HTTP Header oappkey, alternatively, this can be passed as a GET request using the parameter appkey

Additional HeadersReveal

As we are focused on giving the user full control the more information the better. We suggest sending the following headers to make it even clearer where the image came from.

odevice - send the device name, this could just be 'macbook' or more personalised 'steve's macbook'

oplatform - this is the platform used to make the request ie 'ios' or 'macos'

ErrorsReveal

Ovatar.io uses conventional HTTP response codes to indicate the success or failure of an API request. Unless specified otherwise, the endpoint will return a JSON response containing an error code as well as a status for more information about the response.

Code Information
200 Everything worked as expected.
400 Application Key was not sent or is invalid. Your app key is auto generated and can be found in the ovatar.io dashboard.
401 You do not have the privillages access, append or delete specific data.
403 The request limit has been exceeded for the current month.
404 The requested resource could not be found.
405 This request type is not allowed.
422 A parameter is missing or invalid.
500 Something went wrong on Ovatar.io's end (Hopefully never)

OvatarGET /ovatarReveal

The 'Ovatar' endpoint is the primary endpoint for retrieving uploaded images and user data. Content can be retrieved either by a valid phone number or email address or if you are the application owner you can query by 'id'.

By default this data is returned in JSON format, however using the type parameter you can return a user image or placeholder if no image exists.

Querying by email address of phone number will by default check for uploads from your application. If there have been no prior uploads it will fall back to the latest image uploaded. Querying by key will always retrun the only the image from your application.

Each plan has unique request limit. This means you can query the same user unlimited times but each new request will be counted even if no data is returned.

Additional data will be returned depending on your application plan type. For example, if you have the 'premium' plan various EXIF, and added metadata will be returned along with metrics on the queried user. The data structure will also change depending on the application owner too.

Parameters

Parameter Description
(string)query A valid email address or phone number with the country code (+44). This or the id parameter is required
(string)id The id value returned when you upload an image, this is perfered over using query. This or the query parameter is required
(string)type The data can be returned as a json object or as an image. By default image is selected
(boolean)fallback If an email is passed via query has no images accociated with it, ovatar will look for an image hosted on Gravatar. By default this is enabled (true)
(string)placeholder Returned if an image could not be found

default will return an ovatar.io logo as an image.

404will return a 404 header with no body.

customwill return a custom image (which can be set in the dashboard).

jsonwill return a the same as 404 but will return a json object.

(string)size The size of the image retuned

large(350px)

medium(120px) is default

small(25px)

JSON Response Example

[
  {
    "status": "image returned",
    "error_code": 200,
    "output": {
      "application": {
        "name": "Ovatar",
        "url": "http:\/\/orrivo.com",
        "logo": "https:\/\/ovatar.io\/assets\/ovatar_icon.png",
        "signup": "2018-06-30 06:58:16"
      },
      "type": "user",
      "query": "PPwzdstk5g6873buot0a4ram02ljxao-d41d8cd98f00b204e9800998ecf8427e",
      "timestamp": "2018-06-29 11:27:04",
      "host": "ovatar",
      "public": true,
      "id": "PPwzdstk5g6873buot0a4ram02ljxao-d41d8cd98f00b204e9800998ecf8427e",
      "user": {
        "name": "Joe Barbour"
      },
      "captured": "2018:05:23 20:25:58",
      "platform": "mac",
      "camera": {
        "fnumber": "12\/5",
        "exposure": "1\/20",
        "flash": "16",
        "camera_iso": "160",
        "make": "Apple",
        "device": "iPhone X",
        "software": "Photos 3.0"
      },
      "location": {
        "latitude": "9.7122083333333",
        "longitude": "99.987052777778"
      },
      "private": "0"
    }
  }
  ]

OvatarDELETE /ovatarReveal

Along with being able to return image and other data, the ovatar endpoint also allows for the deletion of content that was uploaded by application, or the ability report content that was not uploaded by your application.

Parameters

Parameter Description
(string)query A valid email address or phone number with the country code (+44). This or the id parameter is required
(string)id The id value returned when you upload an image, this is perfered over using query. This or the query parameter is required
(string)reason This is a short text-based summary as to why the image has been reported/removed. E.g 'This image contains nudity'.

UploadPOST /uploadReveal

Uploading new avatars to your application can be done via the upload endpoint. It requires a image and valid phone number and/or email address

It is suggested that you reduce a file size prior to uploading an image file to improve the response time, however it is not necessary. Nor is it required to resize or crop an image, this is all server side.

Ovatar only supports one image per user, per application. If you upload more than one the older image will be overwritten.

POST data must be passed as a JSON object. Images should also be encoded to Base64. Unencoded data will be rejected by the server.

{"ovatar":"[BASE64_DATA]","user":"steve@apple.com|+448774720038"}

Parameters

Parameter Description
(string)user A valid email address or phone number with the country code (+44), or both seporated with a pipe (|). This is required.
(base64)ovatar A PNG, GIF or JPG image encoded Base64 binary data
(string)fullname The users fullname eg Steve Jobs. Not required.
(boolean)private If set to true the uploaded image will only accessed by only your application, not publically like it is by default. This option is available to those with an unlimited plan

JSON Response Example

[
 {
  "status": "image uploaded",
  "error_code": 200,
  "output": {
    "phone": "+44810283847182",
    "email": "test@ovatar.com",
    "id": "PPwzdstk5g6873buot0a4ram02ljxao"
  }
 }
]

iOS Intergration

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

OR

by adding adding the project though Coccopods (Recommended)

pod 'Ovatar-iOS'

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 imageDownloadWithQuery:@"user@email.com"];

    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.

    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