New service creator's guidelines

Vilém Kurz edited this page Dec 30, 2015 · 18 revisions

The new service should inherit as much functionality as possible from ShareKit's base classes. This is crucial for maintainability of the ShareKit:

  • SHKOAuthSharer for services using OAuth for authentication, except those providing their own sdk with OAuth implementation
  • SHKiOSSharer for services using builtin iOS social.framework, such as Twitter, Facebook, SinaWeibo
  • SHKSharer for all other services

For creating a new service, use updated service templates. You can read through them and create new sharer easily as you go. If you want to dig deeper, there is a lot of useful and (sometimes) valid info in original old developer's guidelines. Here is a couple of further advices, which are specific to ShareKit 2.x:

  • Check the demo app, accounts view. When you start making new sharer, first make sure, that authentication is solid. This means implementing login, logoff, user info (see SHKFlickr, SHKiOSTwitter, SHKDropbox or SHKGooglePlus for inspiration). Only after making sure your new sharer works well with accounts view within the demo app, continue with the sharing content.

  • ShareKit is now subproject, and each sharer has its own target. Do not forget to:

    • create a new target for your sharer (you can copy any existing target and adjust).
    • add your new target to convenience libShareKit (Static Library) target. For more info see granular install, or the demo project.
  • The place to add app's API keys is primarily DefaultSHKConfigurator.m . Old Config.h way of configuring ShareKit is removed. Please add API keys for ShareKit demo app - this will greatly simplify maintenance of ShareKit.

  • Sometimes programmers need to show logged in usernames somewhere in the app. If the service uses OAuth v1 for authentication, this info is not stored locally - we need to fetch it from the service after successful login. We introduced new SHKItem's shareType SHKShareTypeUserInfo. If your service uses OAuth v1, please implement it. Look at SHKTwitter, or SHKFacebook to get an idea. Not needed for OAuth2 services - they include username with token.

  • For better understanding of ShareKit flow there are ShareKit's flowcharts in the documents folder. Pay attention to blue objects, everything else should be handled by the ShareKit framework.

  • before using a new UI string, please look at existing strings in localizable.strings. The english file is the definite list of strings used in ShareKit so far. If you decide to use existing string, there is no need to translate it, and your sharer is already localized in all supported languages. If you really need to add new strings, please add them to the end of english localizable.strings in new paragraph and comment what sharer they are for, so that it is easier for translators to find what's new to translate.

  • update podspec for Cocoapods - add new version of podspec file to the CocoaPods/Specs repo.

  • Prepare new sharer for the fact user can revoke access on the service for the app. If the sharer encounters this, it should call - (void)shouldReloginWithPendingAction:(SHKSharerPendingAction)action. See how it is implemented in existing sharers. Using this auth view is presented instead of alert, and share continues automatically after successful login.