Ostetso Integration

Table of Contents

  1. Overview
  2. Register
  3. Fill out the App Information form
  4. Download & install the SDK
  5. Project Configuration
  6. App Configuration
  7. Ostetso Delegate
  8. Add Ostetso actions
  9. iOS 9 App Transport Security
  10. Customization
  11. Administration

1. Overview

By integrating the Ostetso framework into your iOS application you will provide your users with a variety of new functionality including the ability to:

  1. Share their photos/images to a public Gallery, where other users of your app will be able to see, share, Like and (coming soon) comment on them.
  2. Register with a username/password so their identity is consistent within the app across all of their devices, and within any other applications that also use the Ostetso framework

At the same time you, as the owner of the application, will be able to:

  1. Promote particularly noteworthy content within the Gallery.
  2. Monitor/moderate the content to remove any images that may be inappropriate or to ban any users who have uploaded such content.
  3. Push messages to your entire user base with pertinent messages such as new functionality within the app, etc.
Note: The ability to send your users Push Notifications assumes the user has allowed notifications for your app in their device’s Settings. Users also have control over what sort of push messaging they wish to receive via the Ostetso login page.

The Ostetso framework can automatically message users (again, subject to their device settings) when any of their content has had some sort of social activity around it. For example, if someone has posted an image and another user ‘Likes’ it, the user who owns the image will be notified immediately and provided a link that re-opens the app and takes them to the image where the activity occurred.

The Ostetso framework also allows you to better manage how images are shared outside of the app, via email, SMS message, Facebook,Twitter, etc. Rather than simply pushing an image to these services, we provide a link to a dynamically-generated webpage that not only features the image in question but also makes it clear which app (yours!) generated the image and provides a direct link to your app on the App Store.

The integration process itself is designed to be as easy as possible, with basic setup complete in just a few minutes, and will involve the following steps:

  1. Sign up and provide us information about your app including things like it’s name, App Store ID, etc. You’ll also need to provide artwork (app store icons) for your app.
  2. Once you’ve given us this information you’ll be ready to download the SDK, which is a zip file containing the framework you’ll be adding to the Xcode project for your app.
  3. Integrating the framework will involve copying some files into your Xcode project and then choosing where, within your app, you’ll add buttons to share images or view the image-sharing Gallery.

These steps are described in more detail below. But before you get started, you may went to see Ostetso in action. Go ahead and download one of our partner apps as listed on this page. Incidentally, the app named Share Pictures (download here) is actually our sample app (we’ll refer to it more below) and in fact you can grab the complete source-code for this app from Github, here.

2. Register

The first thing you’ll need to do is create an account for yourself via the Sign up page. (We’ll send you an email to the address you provide where you can confirm your account details.)

3. Fill out the App Information form

Once you Login, you’ll be taken to your Dashboard with a list of all your Ostetso-enabled apps. Since you’re just getting started this list will be empty so add your first app using the big ‘Add New App’ button.

From there you can get started filling in the App Information for that app. We’ll need some basic information like the app name (which doesn’t have to match the App store name exactly, and in fact we limit the name length to only 20 characters), the URL of your app in the store, etc. Don’t worry if you don’t have all the information needed right now - you can still continue the integration process and test within a sandbox environment without having everything filled-in.

You’ll also notice that an app-specific ID and Key have been generated for you - we’ll discuss how you use these in just a bit. Once you’ve filled in your basic app information, make sure you hit Save so it will all be recorded to the Ostetso database.

4. Download & Install the Ostetso iOS SDK

Now it’s time to download the Ostetso library that you’ll be integrating into your app. You can download this zip file by Clicking Here (And from this point on in the documentation we’ll be showing some examples for how Ostetso is integrated into an app by using our sample app ‘SharePictures’.)

The first step after downloading the SDK is to unzip it and copy the framework to somewhere that your app can include and link to it, probably into the same folder as your .xcodeproj file.

You should also then drag both the framework and bundle files from the Finder into your project (you can also just drag the entire Ostetso folder to get both at the same time).

If you are upgrading from a previous version of the Ostetso SDK, simply replace the old Ostetso.bundle and Ostetso.framework files with the updated ones.

Go to your project settings and ensure that in the "Copy Bundle Resources" step in your Build phases that the Ostetso.bundle is included in that list. If not, drag Ostetso.bundle into this list so that it appears as below.

5. Project Configuration

We require that you add a linker flag so please add "-ObjC" to the “Other Linker Flags” build settings. If you don’t do this your app will likely immediately crash when launching the Gallery because certain class categories will not be found.

6. App Configuration

When your app is launched, Ostetso must be initialized and authenticated from within your app. In order to authenticate your app with Ostetso you must provide the two values that were presented to you when you first added your app back in Step 3 (and can be found via your app’s page from the Dashboard)

The first ID is the App ID, which is the value that is used to uniquely identify your app.

The second value is your private App Key. This is used to authenticate your app with our server and it is important that you keep this key private and do not share it with others. Treat it as you would any other password that you would use to access a secure website.

To properly integrate Ostetso into your app you start by importing the Ostetso header file into your app’s App Delegate implementation file:

#import "Ostetso/Ostetso.h"
The first thing that then needs to happen once your app is launched is to call:
[Ostetso setApplicationID:appKey:useProductionEnvironment:delegate]
You must call this from within your app delegate’s [application didFinishLaunchingWithOptions] method. This is where you are providing Ostetso with the identity and authentication credentials that it needs to function properly.

Here’s some more information about the parameters to this method:

[Ostetso setApplicationID : (NSString *) appID
                   appKey : (NSString *) appKey
 useProductionEnvironment : (BOOL) useProductionEnvironment 
                 delegate : (id<OstetsoDelegate>) delegate]
appID Provide the App ID that was provided to you on the Ostetso.com developer page for your App.
appKey Provide the App Key that was provided to you on the Ostetso.com developer page for your App.
useProductionEnvironment Here you will also tell Ostetso whether you are running in full Production mode or just within the Sandbox test environment. Initially you’ll pass NO for useProductionEnvironment to stay within the Sandbox.

When you first created your app on Ostetso.com your app was automatically given access to the Sandbox environment and you MUST only run in that environment until your app has been approved to run under the Production environment. (if you change this to YES prior to approval, you’ll simply get an error message in the console and Ostetso won’t work).

Note: This approval process is only something you need to do once for each app. Once you’ve done an initial Ostetso integration and we can confirm everything is set up properly you’ll be able to switch back and forth between Sandbox and Production modes at any time and for any future builds.

We do ask that you integrate and test Ostetso in your app thoroughly using the Sandbox environment before going back to your app’s page on Ostetso.com and selecting “Submit for production.” Once you are ready, go ahead and do that and the Ostetso team will review your app and then notify you when it has been approved for the production environment. There’s more information about how to submit to the production environment available here.

The final parameter, delegate, is optional and can be nil but this allows you to pass an OstetsoDelegate to the above method. Providing the delegate to Ostetso will allow you to receive callbacks when certain events occur. We strongly recommend you provide an OstetsoDelegate in order to provide the best experience for your users. The delegate integration is discussed in the next section.

At the very end of your didFinishLaunchingWithOptions method you must add a call to tell Ostetso that your app has finished launching and pass along the launchOptions that were provided to your didFinishLaunchingWithOptions method. That looks like this:

[Ostetso applicationDidFinishLaunchingWithOptions: launchOptions];
Now that Ostetso initialization is taken care of, you must make a few more modifications to your app delegate implementation.

Depending on what your app does, it’s possible that you have already added the handleURL method to your delegate. If so, you will need to add a call to [Ostetso handleURL: url] where url is the url parameter that was originally passed into the app delegate handleURL method. If you have not already implemented the app delegate handleURL method, simply add the following code to your app delegate...

- (BOOL)application : (UIApplication *)application
            openURL : (NSURL *)url
  sourceApplication : (NSString *)sourceApplication
         annotation : (id)annotation
{
    return [Ostetso handleURL: url];
}

Ostetso is designed to handle all remote push notifications for you, so you will need to add a few more methods to your app delegate that will provide Ostetso with the necessary data to configure and process push notifications. Simply copy and paste the following methods into your app delegate source file:

#pragma mark Push notifications
- (void) application : (UIApplication*)application 
didRegisterForRemoteNotificationsWithDeviceToken : (NSData*)pushToken
 {
     [Ostetso registerPushToken: pushToken];
 }

- (void) application : (UIApplication*)application 
didReceiveRemoteNotification : (NSDictionary*)userInfo
 {
     [Ostetso didReceiveRemoteNotification: userInfo];
 }

- (void) application : (UIApplication*)application 
didFailToRegisterForRemoteNotificationsWithError : (NSError*)error
 {
 #if !TARGET_IPHONE_SIMULATOR
     NSLog(@"Failed to get push token, with error:%@", error);
 #endif
 }
Finally, push notifications need to be properly configured with Apple via the Apple Developer Member Center. Please see the Push Notification Configuration page for a description of this process.

7. Ostetso Delegate

Ostetso uses the OstetsoDelegate to communicate back to your app when certain events or actions have occurred. We strongly recommend that you implement the OstetsoDelegate but it is not required and Ostetso can function properly without it.

As mentioned in the previous section, if you choose to implement an Ostetso delegate, an instance of it should be provided when you initialize and authenticate Ostetso.

The first two methods are the most important and we highly recommend that you implement these as they give a better user experience for your customers with regard to push notifications.

If a push notification is delivered to your app while it is running you know much better than Ostetso does about how and when to tell your user about it. For example, if the user is in the middle of executing a paint stroke it is not appropriate to interrupt them to display a push notification. To deal with this we have provided two delegate callbacks to allow you to inform your users about a received push notification. They are:

- (void) setNotificationsPending: (BOOL) hasPendingNotifications;
and
- (void) notificationReceived: (NSString *)message;

The first, setNotificationsPending, is called by Ostetso when a push notification has been delivered to your app and the user has yet to read it ( hasPendingNotifications will be set to YES ). This will also be called again after a user has read any pending notification messages (and then hasPendingNotifications will be NO ).

Because the user will read notification messages by accessing the Gallery, we recommend that you provide an indicator on your Gallery button showing that there are pending notifications and then remove the indicator once those notifications have been read. See the next section for more details on this.

The second method, which is related to push notifications, is notificationReceived . This will be called when there is a simple text message to display to your user. When you receive this call, display the textual string provided in “message” whenever it is convenient for you to do so. A simple UIAlertView is usually best.

Finally, there are three more methods you may find useful:

- (void) shareComplete         : (NSError *) error;
- (void) galleryComplete       : (BOOL) successful;
- (void) uploadFailedWithError : (NSError *) error;

Details about these three are as follows:

- (void) shareComplete: (NSError *) error;
This is provided to notify you that the share view has been dismissed so your app can continue functioning as it normally would. For example, you may want to resume a live camera capture session.

- (void) galleryComplete: (BOOL) successful;
This is provided to notify you that the Gallery view has been dismissed so your app can continue functioning as it normally would. For example, you may want to resume a live camera capture session.

- (void) uploadFailedWithError: (NSError *) error;
This is provided to notify you that an image upload failed as would happen if you called [Ostetso shareImage] and there is no access to the internet. Ostetso will already display an error message for this situation, but we provide this explicit method in case there is another action that you wish to perform, such as caching the image and attempting to share it again later when the connection has been restored.

If you would like to see an example of an OstetsoDelegate implementation, take a look at the HomeViewController class in our example project SharePictures on Github.

8. Add Ostetso actions

Now that the Ostetso framework is properly integrated, you now need to decide how your users will interact with it. There are two primary items to be dealt with:

  1. Give your users a method to pass images to Ostetso so they can be viewed in the Gallery or shared externally.
  2. Add a button or workflow that allows your users to go directly to the Ostetso Gallery so they can see what other users have created.

For the first, you’ll pass an image from your app to Ostetso via the use of the following method:

[Ostetso shareImage: <some_ui_image>];
This will push the image to our server and add it to our database. From the user’s perspective, once this command is executed they’ll be presented with the Ostetso Sharing Page, which looks like this:
Note: If you’re looking at this page in the iOS simulator running on your Mac you may notice rendering problems, specifically some overlapping icons. This is apparently a bug in the simulator, and you won’t see these problems when running on actual iOS devices.

This Sharing page serves multiple purposes. It allows the user to choose whether their image will be visible publicly in the Gallery, or if they want to keep it private.

(A user will still see their own Private images when they visit the Gallery, but there will be an obvious badge in the upper-right corner of the image indicating that it’s not visible to the rest of the world).

The Sharing page also provides a mechanism for sharing the image externally via an app-specific web-page. (Here’s an example of what that looks like).

One of the enhanced sharing services we provide is to Facebook, and you’ll need to do some specific configuration with them to make all this work properly. See the Facebook Configuration section for more details. Facebook sharing is not required and if you do not do the Facebook configuration Ostetso will simply not present the Facebook option. If you’d like to get started with Ostetso without Facebook integration, go ahead. You can always add it in later.

Typically, entry to the Sharing page is via a traditional ‘share’ button. Most developers simply replace the call to Apple’s ShareSheet with the call to [Ostetso shareImage:] instead.

As you can see in the image above, there is a button on the Sharing page that will take your user directly to the Gallery. Once there they’ll see the image they just posted, as well as the latest images from other users. You’ll probably want your users to be able to visit the Gallery without sharing an image too, and for that we provide the following call:

[Ostetso showGallery]
While this provides quick access to the Gallery, there’s one additional thing we recommend you do to provide some more functionality to your Gallery button.

If you set up the recommended setNotificationsPending: method described in the previous section, you can use that to display an alternate Gallery button with some type of indication that the user has unseen notifications. (If there are pending notifications then the hasPendingNotifications parameter will be YES ).

For the SharePictures example app we use a Gallery button with a red badge indicator in the corner. Sample Gallery icons, with and without badges, can be dowloaded from www.ostetso.com/developerAssets

Once the user has viewed the unseen notifications we call setNotificationsPending again with hasPendingNotifications set to NO so that the app can revert back to the normal Gallery button. Again, this feature is optional, but we believe it is an important tool for encouraging your users to engage more deeply with the community.

It’s up to you as to where in your app you want to provide the ability to view the Gallery but we recommend someplace (or multiple places) that is/are visited frequently. You’ll find that allowing your users to interact with others as much as possible will result in much greater engagement with your app, as well as driving additional downloads as they share externally.

One final note: Both [Ostetso shareImage:] and [Ostetso showGallery] will present a full screen UIView to the user. By default these views are displayed as a child of the topmost view in your app at the time that they are executed. It is important that you do not hide or destroy your topmost view while the view provided by Ostetso is visible. If you need to get notified when the Ostetso provided view has been dismissed you can implement the appropriate OstetsoDelegate method (either shareComplete or galleryComplete depending on which of the Ostetso Actions you have called).

9. iOS 9 App Transport Security

As part of iOS 9 Apple introduced App Transport Security (see Apple’s documentation) as part of a new and improved security model. Ostetso has been developed with this in mind and has built-in support for ATS already. However, Ostetso relies on some 3rd party SDKs that are not yet ATS compliant. If you are developing your app using the iOS 9 SDK (or newer) you will need to make a few additions to your project configuration in order for Ostetso to work properly.

First, edit the build settings your app target and find the “Enable Bitcode” setting. Make sure that this value is set to “No."

Next, in the project navigator in Xcode find your app’s Info.plist file. Control-click on the plist file in the list and select “Open As -> Source Code”. In the source code editor paste the following code making sure that it is placed within the existing plist and dict groups:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>facebook.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionRequiresForwardSecrecy</key>
            <false/>
        </dict>
        <key>fbcdn.net</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionRequiresForwardSecrecy</key>
            <false/>
        </dict>
        <key>akamaihd.net</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionRequiresForwardSecrecy</key>
            <false/>
        </dict>
        <key>s3.amazonaws.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionRequiresForwardSecrecy</key>
            <false/>
        </dict>
    </dict>
</dict>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fbapi</string>
    <string>fbapi20130214</string>
    <string>fbapi20130410</string>
    <string>fbapi20140410</string>
    <string>fbapi20140116</string>
    <string>fbapi20150313</string>
    <string>fbapi20150629</string>
    <string>fbauth</string>
    <string>fbauth2</string>
    <string>fb-messenger-api20140430</string>
    <string>instagram</string>
</array>
                

An easy test to see that you have this configured properly is to launch Ostetso and view the gallery. If the images are showing up as grey boxes and you are getting a lot of console error message then something is not correct. Double-check that you have inserted the above code in the correct place in the plist file.

10. Customization

The graphic elements of the Ostetso Gallery can all be modified in order to make everything conform to the same design aesthetic as the rest of your app. We strongly recommend that you take advantage of this since this will make the Gallery feel like it’s a natural part of your app and not a separate thing.

All of the things you can modify are shown in the Ostetso.h file, within the section labeled Ostetso User Interface Customization Settings) Things like border and button colors, border styles, etc., can all be customized within this file by overriding the default values. The buttons at the top of the Gallery as well as the ‘Like’ and ‘Share’ buttons on every image can also be replaced.

You override the default values by calling the method in question somewhere after you’ve initialized Ostetso with the setApplicationID call.

So, for example, if you wanted to change the border color on every image in the Gallery to be a dark red, and you wanted to replace the default ‘heart’ artwork we use for the Like button with something you’ve designed yourself, you would use the following to deal with the border color change:

[Ostetso setGalleryBackgroundColor: [UIColor colorWithRed:.4 green:0 blue:0 alpha:1]];
and then you would pass the image you want to use as the new Like button via:
[Ostetso setLikeButtonImg: img];
where img is a UIimage instance. We expect any replacement image you pass in to be the same size as the originals, which are all available here.

11. Administration

The Ostetso framework allows for a specific username to be designated as the Administrator for that app. This Administrator will have access to additional features and information that other users do not. For example, as an Administrator you'll be able to promote certain images (‘boost’) so more of your users will see them, remove images from view, and even ban users that aren't behaving according to whatever community standards you choose to enforce.

Simply log into Ostetso from within your app using the same credentials (username and password) that you have already used to register on this website, and you will be granted these administrative privileges. You then access these features via the ‘more’ button that is available for every image. So, for any image in the Gallery, touch on it so it becomes full-screen, and then touch the ‘...’ button in the bottom-right corner of the image:

Instead of the menu that a regular user would see (where they can flag content that they find objectionable) you’ll see a variety of statistics about the image in question and information about the user who posted the image. Here’s an example of what that might look like:

In addition to the information about the image and who created it, you can also:

  1. Remove a user

    Removing or banning a user will mean that the other users of your app will no longer see any content from this user. The removed user will actually be able to continue using the app, but any photos they try to post to the Gallery will be kept Private, and thus visible only to the banned user.

  2. Remove an image

    Removing an image will mean that the users of your app will no longer see this image in the Gallery. The person who generated the image will, however, still see this image in their own view of the Gallery and will be able to share this image outside of the app via Mail, Facebook, etc.

  3. Boost an image

    The Gallery in Ostetso is ordered based on a combination of several factors - recency, social activity, etc. However sometimes you may see an image in the Gallery that you feel would be of particular interest to your users and you’d like to increase its visibility. For this reason we have provided the ability to ‘Boost’ an image so it appears at the top of the Gallery.

    Boost values will decay over time, until they reach zero.

    You can only Boost images that were created with your apps. If you open the administrative panel for an image that was created with a different app, you’ll notice that the ‘Boost this image’ button is grayed-out and inaccessible.

    You may also choose a negative Boost value, which will keep the image in the Gallery but deprioritize it significantly, effectively ‘burying’ it so it’s not going to be seen by many users. In contrast to actually removing an image, the negative Boost capability is designed to be used for images that just aren’t that interesting or pretty. It’s simply another tool for helping to curate your community’s Gallery.

    Ultimately whether you choose to use the ‘Boost’ capability at all is up to you. You may find that it helps increase engagement with your app, or you may find that the default algorithms work just fine already.

Finally, as an app Administrator, when you install your app on your iOS device and log in with your developer account, you will receive push notifications whenever one of your users “flags” an image as inappropriate. (They can do this by selecting the “...” next to the image when it is in single column view and then clicking “Report as inappropriate” button). Additionally, when logged into your app as an Administrator you can filter your gallery view on ‘Flagged’ images, which will give you the opportunity to remove the images, ban the user or just clear the flag.