This will help you get started with Tapglue on iOS step by step guide.
A more detailed documentation can be found on our documentation website.
If you're interested in the iOS SDK Reference Documentation visit our docs on CocoaPods.
To start using the Tapglue API you need an APP_TOKEN
. Visit our Dashboard and login with your credentials or create a new account.
Our Sample app covers most of the concepts in our SDK and is a great showcase if you want to check implementation details.
This page will help you get started with Tapglue on iOS step by step guide.
To install Tapglue with CocoaPods:
- Install CocoaPods with
gem install cocoapods
- Run
pod setup
to create a local CocoaPods spec mirror, if this is the first time using CocoaPods. - Create a
Podfile
in your Xcode project and add:
pod 'Tapglue'
- Run
pod install
in your project directory and Tapglue will be downloaded and installed. - Restart your Xcode project
To install Tapglue with Carthage:
- Install Carthage with
brew update
followed bybrew install Carthage
- Create a Cartfile in the root of your project
- Add the following line to your Cartfile:
github "Tapglue/ios_sdk" ~> 2.0.1
- Run
Carthage update --platform iOS
- Copy binaries into your project, for RxSwift you only need the RxSwift framework file (not RxTest and RxBlocking)
If you don't want to use CocoaPods you download the latest version of Tapglue from Github and copy it into your project.
- Clone the SDK with
git clone https://github.com/tapglue/ios_sdk.git
- Copy the SDK into your Xcode project's folder
- Import all dependencies
To start using Tapglue, you must initialise our SDK with your app token first. You can find your app token in the Tapglue dashboard.
To instantiate Tapglue, simply call the constructor and pass in a Configuration instance with your settings. We recommend having the configuration set at a central place and reuse it, for example in the app delegate.
If you want to initialise SDK with a custom configuration you can specify following attributes:
baseUrl
appToken
log
The following example showcases usage of the configuration and instantiation of Tapglue.
import Tapglue
let configuration = Configuration()
configuration.baseUrl = "https://api.tapglue.com"
configuration.appToken = "your app token"
// setting this to true makes the sdk print http requests and responses
configuration.log = true
let tapglue = Tapglue(configuration: configuration)
let rxTapglue = RxTapglue(configuration: configuration)
We offer two implementations of Tapglue, a default one with callbacks and one that returns RxSwift Observables.
If you plan to use our Notification Service Signals, add the following to the configuration in your app delegate.
sims = TapglueSims(appToken: appToken, url: url, environment: .Sandbox)
registerForPushNotifications(application)
Tapglue.setSessionTokenNotifier(sims)
Last you just need to provide us your push certificate and configure the parameters.
Parameter | Description | Example |
---|---|---|
url |
URL where the token should register. | https://api.tapglue.com |
environment |
.Sandbox or .Production depending on the environment of your certificate. |
.Sandbox |
The framework is compatible with iOS 8.0 and up
The SDK offers two interfaces with the exact same functionality. One of them uses callbacks to return results, the other uses RxSwift Observables. If you want to learn more about RxSwift you can read more about it here
If you're familiar to RxSwift and FRP the interactions with the Rx interface are obvious. For the callbacks we always have a similar way of expressing it, for API calls that return entities (users, posts, etc) the methods expect a block with the signature:
(entity: Entity?, error: ErrorType?) -> ()
When the API request doesn't return an entity the signature will look like:
(success: Bool, error: ErrorType?) -> ()
Our SDK provides paginated endpoints. This means you potentially have to paginate through several pages to get all the information from an endpoint. This applies to endpoints that return data in a list form. The previous page represents content older than the current page.
tapglue.retrieveFollowers() { (page:Page<User>?, error:Error?) in
}
given you have a page and you want the previous:
page.previous() { (page:Page<User>?, error: Error?) in
secondPage = page
}
tapglue.retrieveFollowers().subscribe(onNext: {(page:RxPage<User>) in
})
given you have a page and you want the previous:
page.previous().subscribe(onNext: {(page:RxPage<User>) in
})
After installing Tapglue into your iOS app, creating users is usually the first thing you need to do, to build the basis for your news feed.
let user = User()
user.username = "some username"
user.password = "some password"
tapglue.createUser(user) { user, error in
}
//RxSwift
tapglue.createUser(user).subscribe()
There are two ways to login a user: by username or by email. Here's an example of loging in with a username:
tapglue.loginUser("username", password: "password") { user, error in
}
//RxSwift
tapglue.loginUser("username", password: "password").subscribe()
Creating a user no longer will log the user in.
To logout the current user call logout
.
tapglue.logout() { success, error in
}
//RxSwift
tapglue.logout().subscribe()
When you successfully login a user, we store it as the currentUser
by default. The current user is a property on the Tapglue
and RxTapglue
instances. Once logged in it is persisted and can be refreshed by calling refreshCurrentUser()
var currentUser = tapglue.currentUser
//refreshing the current user
tapglue.refreshCurrentUser() {user, error in
if let user = user {
currentUser = user
}
}
//refreshing the current user in RxSwift
tapglue.refreshCurrentUser().subscribeNext {user in
currentUser = user
}
To update the current user call updateCurrentUser(user: User)
.
let user = tapglue.currentUser
user.email = "new@email.com"
tapglue.updateCurrentUser(user) {user, error in
}
//RxSwift
tapglue.updateCurrentUser(user).subscribe()
This will delete the user from Tapglue. The user cannot be retrieved again after this actions.
tapglue.deleteCurrentUser() { success, error in
}
//RxSwift
tapglue.deleteCurrentUser().subscribe()
Connecting users and building a social graph is one of the most challenging parts of building a social experience. We provide three simple ways to help you get started.
One way to create connections between users within your app is to do a search. This can be achieved with the following:
tapglue.searchUsersForTerm("searchTerm") {users, error in
}
//RxSwift
tapglue.searchUsersForTerm("searchTerm").subscribeNext { users in
}
This will search for the provided term in the username
, firstName
, lastName
and email
.
If you want to search for multiple e-mails and get back a list of users. This is usually the case when you want to sync users from a source like the address-book. To do so use the following:
tapglue.searchEmails(emails) {users, error in
}
//RxSwift
tapglue.searchEmails(emails).subscribeNext {users in
}
A similar behaviour can be achieved if you want to sync users from another network like Facebook or Twitter.
let ids = ["id1", "id2"]
tapglue.searchSocialIds(ids, onPlatform: "facebook") { users, error in
}
//RxSwift
tapglue.searchSocialIds(ids, onPlatform: "facebook").subscribeNext { users in
}
To connect users you have to create a Connection entity. The connection entity consists of a userId
a ConnectionType
and a ConnectionState
. The user id represents who the connection is to, the ConnectionType
can be of type Follow
or Friend
and the ConnectionState
can be either Pending
for when a request has to be accepted by the other party, Confirmed
if it does not need to be accepted, or Rejected
if the other party rejected the request.
When a Connection
request is received from another user in a Pending
state, you can then respond by setting the ConnectionState
to Confirmed
let connection = Connection(toUserId: "userId", type: .Follow, state: .Confirmed)
tapglue.createConnection(connection) { connection, error in
}
//RxSwift
tapglue.createConnection(connection).subscribeNext { connection in
}
tapglue.deleteConnection(toUserId: "123", type: .Follow) { success, error in
}
//RxSwift
tapglue.deleteConnection(toUserId: "123", type: .Follow).subscribeNext { _ in
}
You can learn more about deleting connections etc. in the reference documentation below.
Events are very powerful to build Notification centers or activity feeds. However, if you wan't to include user generated content to build a proper news feed we provide a much more powerful entity for you: Posts
.
To create a post you need to specify two things first: Visibility and attachments. The possible values for visibility are .Private
(only visible for the creator), .Connections
(only visible for the connections of the creator and the creator), and .Public
(visible for everybody).
Each post can have multiple attachments. An attachments of a post can currently be of type text or a url. A text can be used to represent the user generated text. A url is useful for different use-case such as a reference to an image or video. Furthermore you can specify a name for each attachments to add more context to the post.
The contents property of the Attachment entity is a dictionary where the key represents a BCP47 encoded language and the value the content (text, url or image)
let attachment = Attamchment(contents: ["en":"some content"], name: "my attachment", type: .Text)
So putting the last couple of concepts creating a post is pretty straight forward:
let attachment = Attamchment(contents: ["en":"some content"], name: "my attachment", type: .Text)
let post = Post(visibility: .Connections, attachments: [attachment])
tapglue.createPost(post) { post, error in
}
//RxSwift
tapglue.createPost(post).subscribeNext { post in
}
Posts are the core entity of a news feed. To provide a richer and more engaging experiences, Tapglue enables you to comment or like posts
A comment consists of a dictionary of content, where the keys are BCP47 encoded languages and the values the text (similar to the attachments), and a postId
. To create a comment first you need to create a comment entity and then create it on tapglue.
let comment = Comment(contents: ["en":"my comment"], postId: "postId")
tapglue.createComment(comment) { comment, error in
}
//RxSwift
tapglue.createComment(comment).subscribeNext { comment in
}
To retrieve comments on a post:
tapglue.retrieveComments("postId") { comments, error in
}
//RxSwift
tapglue.retrieveComments("postId").subscribeNext { comments in
}
To update or delete a comment you can use:
updateComment
deleteComment
You can learn more about deleting comments etc. in the reference documentation below.
To like a post you simply have to call createLike
with a post id:
tapglue.createLike(forPostId: "postId") { like, error in
}
//RxSwift
tapglue.createLike(forPostId: "postId").subscribeNext { like in
}
To retrieve likes on a post simply call retrieveLikes
with the post id.
To remove a like call deleteLike
with the id of the previously liked post
In general there are three different types of feeds that Tapglue provides:
- News Feed
- Posts Feed
- Activity Feed
The News Feed contains both: Posts and Activities that have been created in the users social graph. The Posts- and Activity Feeds only contain entries of their associated type.
Additionally Tapglue provides lists of Posts and Activities for a single user.
- User posts
- User Activties
Eventually, there is also the opportunity to query the feeds to only get certain types of events.
When retrieving the news feed you will get to lists: posts
and activities
to do so run:
tapglue.retrieveNewsFeed() { newsFeed, error in
}
//RxSwift
tapglue.retrieveNewsFeed().subscribeNext { newsFeed in
}
To retrieve a Posts Feed there is following method:
tapglue.retrievePostFeed() { posts, error in
}
//RxSwift
tapglue.retrievePostFeed().subscribeNext { posts in
}
Similar to the examples above, you can retrieve an activity feed as shown in the example below:
tapglue.retrieveActivityFeed() { activities, error in
}
//RxSwift
tapglue.retrieveActivtiyFeed().subscribeNext { activities in
}
You can also retrieve the posts of a single user and display them under a profile screen for example.
tapglue.retrievePostsByUser("userId") { posts, error in
}
//RxSwift
tapglue.retrievePostsByUser("userId").subscribeNext { posts in
}
You might want to show friends, follower and following lists to the current user in your app. For this we provide the following methods
retrieveFollowers
retrieveFollowings
These methods can also be applied to other users with:
retrieveFollowersForUserId
retrieveFollowingsForUserId
Here is an example to retrieve all follower of the currentUser:
tapglue.retrieveFollowers() { users, error in
}
//RxSwift
tapglue.retrieveFollowers().subscribeNext { users in
}
You can turn on Tapglue logging by initialising the SDK with a custom configuration and setting enabling the logging there.
let configuration = Configuration()
let configuration.log = true
let tapglue = Tapglue(configuration: configuration)
//RxSwift
let tapglue = RxTapglue(configuration: configuration)
Error handling is an important area when building apps. To always provide the best user-experience to your users we defined TapglueError
.
When using the callbacks most methods will provide you either a value or an error. We recommend to always check the success
or value first and handle errors in case they occur. When using the Rx Observables the errors will get sent on error event.
Each error will contain a code
and a message
. You can use the codes do define the behaviour on certain errors.
This SDK is provided under Apache 2.0 license. For the full license, please see the LICENSE file that ships with this SDK.
TODO: Implement Comments & Likes on external objects