STTwitter 0.2.6
- 由
- Nicolas Seriot, Bavarious, Chris Ricca, Evan Roth, Frank Dowsett, James Howard, Matthew Tomlinson, Pawel Niewiadomski, Sven Weidauer, Thijs Alkemade, Victor Ng, b123400, daisy1754, forcha, germanSancho, ijaycho 和 passwordreset
一个稳定、成熟且全面的Objective-C库，用于Twitter REST API 1.1
类似于Twitter Fabric TwitterKit的开源版本，没有UI部分但具有更多灵活性
还包括适用于OS X功能强大的Twitter开发控制台
[2015-03-28] 已签名OS X演示应用程序构建： STTwitterDemoOSX.app.zip
[2014-06-18] Swifter，由 @MatthewDonnelly 编写的用于iOS和OS X的Swift Twitter框架
[2014-05-31] 关注STTwitter在Twitter： @STTLibrary
[2014-05-22] STTwitter在CocoaHeads Lausanne （链接） 中展出 (幻灯片)
[2013-10-24] STTwitter在SoftShake 2013 （链接） 中展出 (幻灯片)。
用户评论
"我们现在在使用STTwitter" Adium开发者
"一个用于Twitter的HTTP API的Objective-C包装器非常棒？当然!" @nilsou
"您的库真的很出色，我因为某些原因停止了客户端的开发，因为我对Twitter API感到讨厌，这个库让我想继续开发，真心感谢！" MP0w
"通过他自己后端的HTTP调用包装器，STTwitter为您编写了基于OAuth的认证和API资源访问的大部分代码，如状态、提及、用户、搜索、朋友&Followers、收藏、列表、位置、趋势。文档也是一流的。" STTwitter - Delightful Twitter Library for iOS / buddingdevelopers.com
在一个项目中开始使用STTwitter。它真是太神奇了。使用起来非常简单。感谢 @nst021 @iOSDevZone
"我在一个WatchKit应用中使用这个库，效果非常好。" inb4ohnoes
"我喜欢STTwitter - 它在构建@entourageio时使事情变得容易。" @_jeffreyjackson
安装
将 STTwitter 目录拖放到您的项目中。
将您的项目与以下框架相关联
- Accounts.framework
- Social.framework
- Twitter.framework（仅限 iOS）
- Security.framework（仅限 OS X）
如果您想使用 CocoaPods，请将以下两行添加到您的 Podfile 中
pod 'STTwitter'
然后，运行以下命令以安装 STTwitter pod
pod install
STTwitter 不依赖于 AppKit 或 UIKit，因此可用于命令行 Twitter 客户端。
STTwitter <= 0.2.2 需要 iOS 5+ 或 OS X 10.7+
STTwitter >= 0.2.3 需要 iOS 7+ 或 OS X 10.9+
Vea Software 提供了一个精彩的现场演示 教程，关于仅使用 STTwitter 创建简单的 iOS 应用。
代码片段
以下是使用 STTwitter 的几种方法。
您可以在 demo_cli 目录中找到完整的、最小化的、命令行项目。
- streaming 使用流 API 过滤包含某些单词的所有推文
- streaming_with_bot 与上述相同，但会从另一个账户即时回复
- reverse_auth 执行反向身份验证
- followers 通过跟随 Twitter 的 API 游标显示您的关注者，并在达到速率限制前等待一段时间
- favorites 显示您关注的用户的点赞推文，设置推文的点赞状态
- conversation 在同一对话中发布几条推文
- t2rss 将您的时间线转换为 RSS 源
实例化 STTwitterAPI
STTwitterAPI *twitter = [STTwitterAPI twitterAPIWithOAuthConsumerKey:@""
consumerSecret:@""
username:@""
password:@""];验证凭据
[twitter verifyCredentialsWithUserSuccessBlock:^(NSString *username, NSString *userID) {
// ...
} errorBlock:^(NSError *error) {
// ...
}];获取时间线状态
[twitter getHomeTimelineSinceID:nil
count:100
successBlock:^(NSArray *statuses) {
// ...
} errorBlock:^(NSError *error) {
// ...
}];流 API
NSObject <STTwitterRequestProtocol> *request = [twitter getStatusesSampleDelimited:nil
stallWarnings:nil
progressBlock:^(id response) {
// ...
} stallWarningBlock:nil
errorBlock:^(NSError *error) {
// ...
}];
// ...
[request cancel]; // when you're done with it仅限应用程序的身份验证
STTwitterAPI *twitter = [STTwitterAPI twitterAPIAppOnlyWithConsumerKey:@""
consumerSecret:@""];
[twitter verifyCredentialsWithUserSuccessBlock:^(NSString *username, NSString *userID) {
[twitter getUserTimelineWithScreenName:@"barackobama"
successBlock:^(NSArray *statuses) {
// ...
} errorBlock:^(NSError *error) {
// ...
}];
} errorBlock:^(NSError *error) {
// ...
}];使用游标枚举结果，根据速率限制暂停
[_twitter fetchAndFollowCursorsForResource:@"followers/ids.json"
HTTPMethod:@"GET"
baseURLString:@"https://api.twitter.com/1.1"
parameters:@{@"screen_name":@"0xcharlie"}
uploadProgressBlock:nil
downloadProgressBlock:nil
successBlock:^(id request, NSDictionary *requestHeaders, NSDictionary *responseHeaders, id response, BOOL morePagesToCome, BOOL *stop) {
NSLog(@"-- success, more to come: %d, %@", morePagesToCome, response);
} pauseBlock:^(NSDate *nextRequestDate) {
NSLog(@"-- rate limit exhausted, nextRequestDate: %@", nextRequestDate);
} errorBlock:^(id request, NSDictionary *requestHeaders, NSDictionary *responseHeaders, NSError *error) {
NSLog(@"-- %@", error);
}];各种 OAuth 连接类型
您可以通过三种方式实例化 STTwitterAPI
- 使用在 OS X 首选项或 iOS 设置中设置的 Twitter 账户
- 使用自定义的
consumer key和consumer secret（四种风味）- 获取一个 URL，获取一个 PIN，将其输入您的应用程序中，获取 oauth 访问令牌
- 设置
username和password，通过 XAuth 获取 oauth 访问令牌，如果应用程序有权限 - 直接设置
oauth token和oauth token secret - 打开 Safari（或如果您更喜欢，可以使用
UIWebView实例），在 Twitter 上进行身份验证，并通过自定义 URL 方案在您的应用程序中接收访问令牌
- 获取一个 URL，获取一个 PIN，将其输入您的应用程序中，获取 oauth 访问令牌
- 使用 仅应用程序 身份验证并获取/使用“Bearer token”
因此，总共有五种情况，因此有五种方法
+ (STTwitterAPI *)twitterAPIOSWithFirstAccount;
+ (STTwitterAPI *)twitterAPIWithOAuthConsumerKey:(NSString *)consumerKey
consumerSecret:(NSString *)consumerSecret;
+ (STTwitterAPI *)twitterAPIWithOAuthConsumerKey:(NSString *)consumerKey
consumerSecret:(NSString *)consumerSecret
username:(NSString *)username
password:(NSString *)password;
+ (STTwitterAPI *)twitterAPIWithOAuthConsumerKey:(NSString *)consumerKey
consumerSecret:(NSString *)consumerSecret
oauthToken:(NSString *)oauthToken
oauthTokenSecret:(NSString *)oauthTokenSecret;
+ (STTwitterAPI *)twitterAPIAppOnlyWithConsumerKey:(NSString *)consumerKey
consumerSecret:(NSString *)consumerSecret;回调 URL
在Safari或网页视图中进行身份验证后，Twitter将带有一些附加参数重定向到回调URL。（请确保您的Twitter应用设置允许使用回调，通过指定一个占位符URL，例如 http://www.cnn.com 来指定。此URL在
- (void)postTokenRequest:(void(^)(NSURL *url, NSString *oauthToken))successBlock
authenticateInsteadOfAuthorize:(BOOL)authenticateInsteadOfAuthorize
forceLogin:(NSNumber *)forceLogin
screenName:(NSString *)screenName
oauthCallback:(NSString *)oauthCallback
errorBlock:(void(^)(NSError *error))errorBlock;
反向身份验证
参考：https://dev.twitter.com/docs/ios/using-reverse-auth
反向身份验证最常见的使用场景是让用户使用他们的OS X或iOS Twitter账户注册/登录到远程服务。
iOS/OSX Twitter Server
--------------> reverse auth.
< - - - - - - - access tokens
-----------------------------> access tokens
<-------------- access Twitter on user's behalf
- - - - - - ->
以下是使用STTwitter进行反向身份验证的方法
STTwitterAPI *twitter = [STTwitterAPI twitterAPIWithOAuthConsumerName:nil
consumerKey:@"CONSUMER_KEY"
consumerSecret:@"CONSUMER_SECRET"];
[twitter postReverseOAuthTokenRequest:^(NSString *authenticationHeader) {
STTwitterAPI *twitterAPIOS = [STTwitterAPI twitterAPIOSWithFirstAccount];
[twitterAPIOS verifyCredentialsWithUserSuccessBlock:^(NSString *username, NSString *userID) {
[twitterAPIOS postReverseAuthAccessTokenWithAuthenticationHeader:authenticationHeader
successBlock:^(NSString *oAuthToken,
NSString *oAuthTokenSecret,
NSString *userID,
NSString *screenName) {
// use the tokens...
} errorBlock:^(NSError *error) {
// ...
}];
} errorBlock:^(NSError *error) {
// ...
}];
} errorBlock:^(NSError *error) {
// ...
}];与一些可读内容相反，您可以从iOS Twitter账户中获取直发消息。
Twitter Digits
https://docs.fabric.io/ios/digits/digits.html
在此流程中，您从消费者令牌和仅应用模式开始，通过验证通过短信发送的PIN验证的电话号码后，结束于访问令牌。
流程是这样的
1. start with consumer tokens
2. get a bearer token (ie. app only mode)
2. get a guest token, (ie. temporary user id)
3. post a phone number, using the guest token
4. post the received PIN code for the phone number, using the guest token
5. receive access tokens in return
参见在STAuthenticationVC.m中的有效示例。
OAuth消费者令牌
在Twitter REST API v1.1中，每个客户端应用程序必须使用消费者密钥和消费者密钥的秘密令牌来验证自己。您可以在Twitter网站上为您的应用请求消费者令牌：https://apps.twitter.com/。
STTwitter示例项目中包含了TwitterClients.plist，您可以在其中输入自己的消费者令牌。
示例/测试项目
在demo_osx中有针对OS X的示例项目，您可以选择如何获取OAuth令牌（见下文）。
2013年10月20日10:35生成的归档文件可在http://seriot.ch/temp/STTwitterDemoOSX.app.zip中找到。
一旦您获取到OAuth令牌，您就可以获取您的个人时间轴并发布新的状态。
另外，在demo_ios中还有一个简单的iOS示例项目。
集成技巧
并发执行
STTwitter应该从主线程使用。HTTP请求是异步执行的，并且回调将确保在主线程上调用。
凭证验证
在每个请求之前无需验证凭证。
不过，当应用程序开始时和在应用程序进入前台时这样做似乎是合理的。
超时
除非另有说明，否则STTwitter将使用底层类的默认超时。
您也可以自己设置超时。
[twitter setTimeoutInSeconds:5.0];
在发行模式下删除断言
代码中有几个断言。在调试模式下它们非常有用，但您不应该在发行版中包含它们。
使用Xcode 5创建的新项目默认情况下已经移除了发行版中的NSAssert逻辑。
在旧项目中，您可以设置编译参数-DNS_BLOCK_ASSERTIONS=1。
推文中的字符数
使用方法-[NSString st_numberOfCharactersInATweet]来告知用户在推文末尾之前的可输入字符数。如果字符串超过了推文的最大长度，该方法也可能返回负值。该方法考虑了缩短的URL长度。
日期格式化器
为了将Twitter JSON中的created_at字段字符串转换为NSDate实例，您可以使用+[NSDateFormatter st_TwitterDateFormatter]。
NSDateFormatter *df = [NSDateFormatter st_TwitterDateFormatter];
NSString *dateString = [d valueForKey:@"created_at"]; // "Sun Jun 28 20:33:01 +0000 2009"
NSDate *date = [df dateFromString:dateString];URL缩短器
为了展开像Twitter的t.co服务这样的缩短URL，可以使用
[STHTTPRequest expandedURLStringForShortenedURLString:@"https://#/tmoxbSfDWc" successBlock:^(NSString *expandedURLString) {
//
} errorBlock:^(NSError *error) {
//
}];API响应文本处理
您可以想要使用Twitter的自己的Objective-C库来进行文本处理：https://github.com/twitter/twitter-text-objc/。
twitter-text-objc为您提供了以下方法等
+ (NSArray*)entitiesInText:(NSString*)text;
+ (NSArray*)URLsInText:(NSString*)text;
+ (NSArray*)hashtagsInText:(NSString*)text checkingURLOverlap:(BOOL)checkingURLOverlap;
+ (NSArray*)symbolsInText:(NSString*)text checkingURLOverlap:(BOOL)checkingURLOverlap;
+ (NSArray*)mentionedScreenNamesInText:(NSString*)text;
+ (NSArray*)mentionsOrListsInText:(NSString*)text;
+ (TwitterTextEntity*)repliedScreenNameInText:(NSString*)text;注销
注销用户的正确方法是设置STTwitterAPI实例为nil。
您将在下次登录时创建一个新的。
布尔参数
Twitter API中有许多可选参数。在STTwitter中，您可以通过传递nil来忽略这些参数。关于布尔参数，STTwitter不能仅仅使用Objective-C的YES和NO因为NO的值和nil（零）相同。因此，布尔参数被包装在NSNumber对象中，这得益于Objective-C字面量，使得它们很容易与布尔值一起使用。因此，与STTwitter一起，您将为Twitter API的可选参数分配@(YES)、$@(NO)或nil之一。
长方法
STTwitter提供对Twitter REST API的完整的、“一对一”的Objective-C前端。这通常会导致长方法名和许多参数。在您的应用程序中，您可能想要在STTwitterAPI之上添加自己的简化方法。一个好的想法是为您的应用程序创建一个Objective-C分类，如下面的代码所示。
STTwitterAPI+MyApp.h
#import "STTwitterAPI.h"
@interface STTwitterAPI (MyApp)
- (void)getStatusesShowID:(NSString *)statusID
successBlock:(void(^)(NSDictionary *status))successBlock
errorBlock:(void(^)(NSError *error))errorBlock;
@endSTTwitterAPI+MyApp.m
#import "STTwitterAPI+MyApp.h"
@implementation STTwitterAPI (MyApp)
- (void)getStatusesShowID:(NSString *)statusID
successBlock:(void(^)(NSDictionary *status))successBlock
errorBlock:(void(^)(NSError *error))errorBlock {
[self getStatusesShowID:statusID
trimUser:@(YES)
includeMyRetweet:nil
includeEntities:@(NO)
successBlock:^(NSDictionary *status) {
successBlock(status);
} errorBlock:^(NSError *error) {
errorBlock(error);
}];
}
@end流请求和连接丢失
当您的iOS应用程序在后台运行一段时间后重新回到前台时，流请求可能会丢失。为了妥善处理这种情况，您可以在错误块中检测到连接丢失，并从那里重新启动流请求。
// ...
} errorBlock:^(NSError *error) {
if([[error domain] isEqualToString:NSURLErrorDomain] && [error code] == NSURLErrorNetworkConnectionLost) {
[self startStreamRequest];
}
}];故障排除
xAuth
Twitter限制了xAuth认证过程，只允许xAuth启用消费者令牌。因此，如果您在访问https://api.twitter.com/oauth/access_token时遇到类似于消费者令牌可能未启用xAuth。的错误，请参阅Twitter网站https://dev.twitter.com/docs/oauth/xauth并与Twitter联系，请求为您的消费者令牌启用xAuth认证过程。
其他内容
请在GitHub上提交问题或使用StackOverflow上的STTwitter标签。
开发者
应用程序仅与 STTwitterAPI 进行交互。
STTwitterAPI 将 Objective-C 方法映射到所有 Twitter API 端点。
您可以使用较少的参数创建自己的便利方法。您也可以直接使用此通用方法
- (id)fetchResource:(NSString *)resource
HTTPMethod:(NSString *)HTTPMethod
baseURLString:(NSString *)baseURLString
parameters:(NSDictionary *)params
uploadProgressBlock:(void(^)(NSInteger bytesWritten, NSInteger totalBytesWritten, NSInteger totalBytesExpectedToWrite))uploadProgressBlock
downloadProgressBlock:(void(^)(NSObject<STTwitterRequestProtocol> *request, id response))downloadProgressBlock
successBlock:(void(^)(NSObject<STTwitterRequestProtocol> *request, NSDictionary *requestHeaders, NSDictionary *responseHeaders, id response))successBlock
errorBlock:(void(^)(NSObject<STTwitterRequestProtocol> *request, NSDictionary *requestHeaders, NSDictionary *responseHeaders, NSError *error))errorBlock;层模型
+------------------------------------------------------------------------+
| Your Application |
+--------------------------------------------------------+---------------+
| STTwitterAPI | STTwitterHTML |
+--------------------------------------------------------+ |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ |
| STTwitterOAuthProtocol | |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ |
+--------------------+----------------+------------------+ |
| STTwitterOS | STTwitterOAuth | STTwitterAppOnly | |
+--------------------+----------------+------------------+---------------+
| STTwitterOSRequest | STHTTPRequest |
+--------------------+---------------------------------------------------+
|
+ Accounts.framework
+ Social.framework
摘要
* STTwitterAPI
- can be instantiated with the authentication mode you want
- provides methods to interact with each Twitter API endpoint
* STTwitterHTML
- a hackish class to login on Twitter by parsing the HTML code and get a PIN
- it can break at anytime, your app should not rely on it in production
* STTwitterOAuthProtocol
- provides generic methods to POST and GET resources on Twitter's hosts
* STTwitterOS
- uses Twitter accounts defined in OS X Preferences or iOS Settings
- uses OS X / iOS frameworks to interact with Twitter API
* STTwitterOSRequest
- block-based wrapper around SLRequest's underlying NSURLRequest
* STTwitterOAuth
- implements OAuth and xAuth authentication
* STTwitterAppOnly
- implements the 'app only' authentication
- https://dev.twitter.com/oauth/application-only
* STHTTPRequest
- block-based wrapper around NSURLConnection
- https://github.com/nst/STHTTPRequest
BSD 3-Clause 许可证
见 LICENCE.txt。