This document is separated into multiple sections. The first section describes:

  • Code Structure describes how the code is structured in YesGraph SDK.
  • Convenience API creates an easy to configure, easy to use API to use YesGraph SDK.

The second section describes specific components of the YesGraph SDK:

  • Share Services are displayed on share sheet and can be interacted with by the user.
    • Contact Sources retrieve contacts from one or multiple sources and are used by invite share service.
    • Address Book implements UI similar to iPhone’s contact book for listing contacts.
    • Networking & Models implements networking logic with YesGraph API.
  • Share Sheet is a custom view controller that displays share services.

This document does not describe all classes/functionalities that YesGraph SDK contains. If you are looking for a specific class, you can search for it in the source code.

Code Structure

Code in YesGraph SDK is divided into multiple groups. The components correspond to folder structure inside the SDK.

  • Address Book - Contains contact list UI that displays contacts form.
  • Core - Contains error codes, constants and share sheet implementation.
  • Library - Contains classes and utility methods for YesGraph SDK.
  • Main - Convenience API’s and configuration API’s.
  • Model - Data models used for YesGraph API communication and local storage.
  • Network - Networking code used for YesGraph API communication.
  • Service - Sharing services that can be used with YesGraph SDK share sheet.
  • Theme - Support for stying and theming share sheet and contact list UI.

Each of the sections contains multiple classes that can also be used separately apart from the SDK. Each component is described separately in sections below.

Convenience API

To make the usage of YesGraph SDK as easy as possible, a simple convenience API is provided. Most of the common usage scenarios can be implemented by using this API. However, for fine grain customization lower level components of the SDK may be used.

Convenience API to YesGraph SDK is implemented in YesGraph class, which provides singleton access to multiple convenience methods. Convenience API also handles authentication of the user and styling of all components.

The example below creates a share sheet with invite service, using the Convenience API.

let shareController = YesGraph.shared().shareSheetControllerForInviteService()
YSGShareSheetController *shareController = [[YesGraph shared] shareSheetControllerForInviteService];

Check other available methods in the source code.

The Convenience API also handles uploading of address book to YesGraph API and is triggered when application is activated (UIApplicationDidBecomeActiveNotification). By default only if contact book was not updated for more than 24 hours, it is uploaded.

Share Services

Share services are the main component of the YesGraph SDK and are displayed by Share Sheet. Each represents a single share point, to where a message can be shared. Share services have a delegate which you can use to specify your own message when required and share service will let your delegate know when sharing was completed. Every share service has a delegate property and your class should implement YSGShareServiceDelegate protocol.

Out of the box, YesGraph SDK provides three share services:

  • YSGFacebookService shares a message to Facebook using iOS built-in Facebook sharing library.
  • YSGTwitterService shares a message to Twitter using iOS built-in Twitter sharing library.
  • YSGInviteService shares a message to a Contact Book contact by either Email or Messages app.

Both Facebook and Twitter service belong to a group of Social Share Services, which are described in detail below.

Social Share Services

Social share services are a special category of share services that include both Facebook and Twitter share services. The basic logic is implemented in YSGSocialService class and uses the iOS Social.framework underneath. This class is abstract and requires a concrete subclass to work.

If you wish to implement another Social Share Service, just subclass YSGSocialService class and specify the type supported by Social.framework, which is stored in serviceType property.

Invite Share Service

Invite Share Service is a share service exclusive to YesGraph SDK. It uses device’s local contact book to retrieve contacts and YesGraph API to correctly rank them and suggest which contacts are most frequently used by the configured user.

Invite Share Service divides email and phone contacts, because each of them use a different messaging method.

Once contacts are selected and invite button is pressed, it will open native MFMailComposeViewController for email contacts and MFMessageComposeViewController for phone number contacts (both available in MessageUI framework).

Invite Share Service is implemented in YSGInviteService class and uses multiple contact sources, address book and networking components.

You can specify how many contact suggestions are displayed (numberOfSuggestions property) by Invite Share Service and you can disable the native messaging and emailing sheets (nativeMessageSheet and nativeEmailSheet properties). In this case, only the delegate methods will be called after Invite button is tapped and you will be given array of contacts that were selected by the user.

Contact Sources

Contact sources are components in YesGraph SDK that retrieve contact list from one or more physical sources.

Contact Sources are effectively part of Invite Share service and can be .

Three contact sources exist in the SDK and are implemented by their appropriate class:

  • YSGLocalContactSource retrieves contacts from local phone address book.
  • YSGCacheContactSource creates a contact list cache and returns contact list from cache.
  • YSGOnlineContactSource works with cached contact list, which is stored from YesGraph API, if available. Otherwise it uses a fallback to Local contact source, if cache is not available.
YSGLocalContactSource

YSGLocalContactSource is a wrapper class that handles all the logic from requesting permission to users address book to fetching local contact list from device’s address book.

Because iOS requires a special user permission to allow access to the contacts, local contact source also handles all permission requests. There are two prompts displayed as alert views. First one is displayed by Local contact source and acts as a proxy, because the second (system one) will only display the alert once per application.

This gives the developer control over when system alert is displayed and it also gives the ability to customize the first alert view. The example below shows how title and message can be customized for your own application on the first contact prompt.

let localContactSource = YSGLocalContactSource()
localContactSource.contactAccessPromptTitle = "Access prompt title"
localContactSource.contactAccessPromptMessage = "Access prompt message"
YSGLocalContactSource *localContactSource = [[YSGLocalContactSource alloc] init];
localContactSource.contactAccessPromptTitle = @"Access prompt title";
localContactSource.contactAccessPromptMessage = @"Access prompt message";

YSGCacheContactSource

YSGCacheContactSource is a basic cache that stores contact list and returns it when fetchContactListWithCompletion: method is called. It uses a simple file-based cache. Cache update and invalidation is handled by the caller.

let cacheContactSource = YSGCacheContactSource()
YSGCacheContactSource* cacheContactSource = [[YSGCacheContactSource alloc] init];

Updating of cache is implemented in YSGOnlineContactSource and is a part of contact source chain.

YSGOnlineContactSource

YSGOnlineContactSource is a contact source that retrieves contact list from local contact cache. It also logs already seen suggestions in the cache and resets them if needed. It implements a basic contact source chain, which has 3 steps:

  1. Contact are retrieved directly from local cache.
  2. If cache is empty, contacts are retrieved from local device address book.
  3. If local address book is used, contacts are uploaded to YesGraph API and ranked accordingly.

When step 2 is reached, the address book permission is required and asked from the user.

YSGOnlineContactSource connects to YesGraph API to upload address book, so it requires a configured YSGClient object, YSGLocalContactSource and YSGCacheContactSource objects for online source to work correctly. If contacts are retrieved either from the cache or API, they are in specific ranked order. The useSuggestions property on YSGContactList is set to true. Only if contacts are retrieved directly from local device address book, suggestions will not be available.

Also a user ID must be set for the YSGOnlineContactSource, so the YesGraph API can connect certain contact with the user.

let onlineContactSource = YSGOnlineContactSource(client: client, localSource: localContactSource, cacheSource: YSGCacheContactSource())
onlineContactSource.userId = userId
YSGOnlineContactSource *onlineContactSource = [[YSGOnlineContactSource alloc] initWithClient:client localSource:localContactSource cacheSource:[YSGCacheContactSource new]];
onlineContactSource.userId = userId;

If user is not known, you can use a random user ID, which you can generate by using YSGUtility class and randomUserId method.

Address Book

Address Book is an user interface component of Invite Share Service that displays a contact list and allows for selection of specific contacts in the list. After selecting the contacts it triggers Invite Share Flow, which displays Messaging or Emailing UI.

Address Book is implemented in YSGAddressBookViewController class. It requires an instance of YSGInviteService to work correctly, since it is very tightly integrated with calling invite service sharing functions.

Address Book component is not meant to be used without Invite Share Service.

Networking & Models

YesGraph SDK includes a networking wrapper class and model objects to communicate with YesGraph API. The pattern is modelled after latest AFNetworking principles and wraps iOS networking API’s NSURLSession in Foundation framework.

Network wrapper is implemented in YSGClient class and provides direct API access to YesGraph API. It requires a YesGraph clientKey property to be set.

YSGClient also uses native model classes to make communication with YesGraph API even easier.

  • YSGContactList represents a list of contacts and offers a simple API to operate with contacts (YSGContact).
  • YSGContact represents a single contact and has properties such as name, emails and phones.
  • YSGRankedContact adds properties for contacts returned from YesGraph API, so ranking can be used to sort contacts.
  • YSGSource represents the current contact source and is used when updating contacts on YesGraph API with YSGOnlineContactSource.

If you have more information available about the logged in user, you can set your own YSGSource in the convenience API using contactOwnerMetadata property. It will help us distinguish user from his contacts.

YesGraph API treats mobile devices as untrusted clients, first you need a trusted backend to generate client keys.

The following methods are available to be called on YSGClient and are implemented in their own categories:

  • fetchAddressBookForUserId:completion:
  • updateAddressBookWithContactList:forUserid:completion:
  • updateInvitesSent:forUserid:completion:
  • updateSuggestionsSeen:forUserid:completion:

Read more about connecting apps Read more about creating client keys Read more about using YesGraph SDK to call YesGraph API endpoints

Share Sheet

Share Sheet is a fully customizable component that displays a custom sharing sheet user interface with defined Share Services.

It is not mandatory to use the YesGraph Share Sheet to use specific Share Services.

It is a UIViewController subclass that can be displayed in UINavigationController hierarchy or modally. If it is displayed modally on iPad, it will be displayed as a form sheet by default.

It is implemented in YSGShareSheetController class and can be created by Convenience API or manually. It requires at least one share service to work.

You can set properties of YSGShareSheetController, to make it better fit with your own application:

  • If referralURL property is set, share sheet will display the URL with a copy button. You can use this URL to generate custom referral URLs that user can copy and paste and share on their own.
  • If you specify a custom shareText it will be displayed on the share sheet.
  • If you specify a custom shareImage it will be displayed above share text.

The following example creates a new instance of share sheet with custom share text, ready to be displayed.

let shareController = YSGShareSheetController (services:[ services ], delegate:nil, theme:nil)
shareController.shareText = "My Sharing Text"
YSGShareSheetController *shareController = [[YSGShareSheetController alloc] initWithServices:@[ services ] delegate:nil theme:nil];
shareController.shareText = @"My Sharing Text";

You can also set a delegate for YSGShareSheetController (implementing YSGShareSheetDelegate protocol), if you want to receive messages from share sheet on certain user actions, such as when a specific share service was selected.

See the source code for all delegate methods