AutoTweet NG User Documentation (Pro and free version)
Version 4.4, Revision Date: 16.08.2010
Here you will find the old documentation for versions before Pro 2.0 and Free 3.0.
This document describes the basic functionality and key features of the 1stMovers AutoTweet NG (next generation) extensions. The AutoTweet product series posts the title and url for new Joomla articles, forum posts etc. automatically as status messages to twitter and/or Facebook (pro version). All AutoTweet extensions are under GPL 2.0.
Working process of AutoTweet: The AutoTweet Extension-Plugins stores the messages in the AutoTweet message queue. Messages in the queue are posted to the active channels by the AutoTweet Automator-Plugin. After posting, the messages are stored in a message log and you can repost or approve them. Also messages with state error are stored in the log.
This documentation contains instructions for the free and the commercial (Pro) version of the AutoTweet NG component. The usage of both versions is similar. The free version is limited to one Twitter account and has no Facebook support. Also not all plugins are available for the free version. All free plugins are working also with the Pro version.
Features
- All plugins are customizable: account, category/section to post for, link position, show section/category, post private articles, post modified articles, exclude sections/categories, use title or text for message, additional static text (e.g. for hashtags), short url service provider (is.gd, bit.ly) etc.
- Works with most SEF extensions. Tested with: sh404sef, JoomSEF, AceSEF and - of course - Joomla! embedded SEF support.
- Automatic support for short URLs.
- Automatic message resending: AutoTweet resends the status message automatically if there is an error on api/server side.
- AutoTweet posts also later published or republished articles.
- AutoTweet NG comes with a backend component. The component logs all posted messages and you can manage and resend this messages in the components backend.
- AutoTweet NG supports articles with present publish date. (This articles are posted automatically when published by Joomla.)
Changes/News in new major releases AutoTweet NG Pro 2.0 / Free 3.0
- New handling for messages and URL: All messages are now queued and posted later by the Automator-Plugin. So the Automator-Plugin MUST be installed and enabled (and you need a little bit traffic on your site to trigger the plugin)! After posting, the messages are stored in a message log and you can repost or approve them. Also messages with state error are stored in the log. This solution is more failsave and should work with all SEF extensions without extra work. Also it is no longer a problem to save the message posts for a long time in the log.
- "Manually mode": Now AutoTweet has an autopublish feature. For each channel and plugin you can select if the messages should be autopublished or approved before sending. This feature is now also available for the free version.
- Notification messages: As suggested by many users, the success messages are now only showed when debug mode is enabled.
- Pro version: New multichannel architecture: Now you can add new channels and so you can post to multiple Twitter and Facebook accounts. Also you can post to a Facebook profile, page and group for the same account.
- Pro version: Use your own app/api key to show your own branding instead the AutoTweet logo/text: As requested by some users you can now also use your own app/api key instead the AutoTweet standard app (works for Twitter and Facebook).
- Pro version: The AutoTweet Latest module is now seperated in two modules. One for selecting the publish mode for each channel and one to show the actual jobs in the queue or the latest posts.
- Free version: Now with full SEF support (also when article is saved in backend).
- Free version: Support for Twitter OAuth.
- Some minor changes: see release notes / change log on download page
Restrictions/Limitations of the free version
- You can post to ONE Twitter account only (No multichannel support).
- No support for Facebook or other channels.
- No support for "Use own App/API"-Feature.
- Some plugins and modules are available for the pro version only (They are included in the subscription for the pro version).
Available AutoTweet NG extensions
AutoTweet NG consists of a (main) component and several plugins and modules. With the component you can manage the posted messages, including error und pending messages. The component provides also the basic services for the plugins. The AutoTweet NG Extension-Plugins handles the message posting for the different extensions like Kunena, K2 etc. All Extension-Plugins needs the AutoTweet NG Component (free or pro) to work.
- AutoTweet NG Component: The main component. Message handling and basic services.
- AutoTweet NG Automator-Plugin (is also shipped as part of the component package): All messages are queued and posted later by the Automator-Plugin. So the Automator-Plugin MUST be installed and enabled (and you need a little bit traffic on your site to trigger the plugin)!
- AutoTweet NG Content-Extension (is also shipped as part of the component package): Extends AutoTweet for Joomla core content articles.
- AutoTweet NG Pro Content-Extension (commercial): This plugin is an improved version of the free AutoTweet NG Content-Extension and adds support for ALL extensions that use the Joomla core article table and article generators (Article-Generator, pressetext4Joomla, RSS2Content, 4RSS, generally with all articles added via RSS or XML-RPC, ...). Works also with MyBlog and JReviews. Please follow the instructions on the download page.
- AutoTweet NG Kunena-Extension: Extends AutoTweet for Kunena forum posts.
- AutoTweet NG K2-Extension: Extends AutoTweet for K2 article manager.
- AutoTweet NG Phoca Download-Extension: Extends AutoTweet for Phoca Download and posts a message for new/changed downloads.
- AutoTweet NG Eventlist-Extension: Extends AutoTweet for Eventlist and posts a message for new/changed events.
- AutoTweet NG SimpleCalendar-Extension: Extends AutoTweet for SimpleCalendar and posts a message for new/changed events.
- AutoTweet NG Sobi2-Extension: Extends AutoTweet for Sobi2 article manager and posts a message for new/changed articles.
- AutoTweet NG Remository-Extension: Extends AutoTweet for Remository download manager and posts a message for new/updated downloads.
- AutoTweet NG VirtueMart-Extension (commercial)): Extends AutoTweet for VirtueMart shop system and posts a message for new/updated products.
- AutoTweet NG QuickFAQ-Extension: Extends AutoTweet for QuickFAQ and posts a message for new/updated FAQ entrys.
- AutoTweet NG MyBlog-Extension (commercial): Extends AutoTweet for MyBlog and posts a message for new/updated blog entrys.
- JReviews (via AutoTweet NG Pro Content-Extension): Use the AutoTweet NG Pro Content-Extension (commercial) to post a message for new/updated reviews.
- AutoTweet NG redEVENT-Extension: Extends AutoTweet for redEVENT and posts a message for new/updated events. This is a 3rd party extension by redCOMPONENT. For information see here on JED.
- AutoTweet NG Control Panel Module (commercial): AutoTweet backend control panel. With this module you can toggle the autopublish modes for channels and change other options form the backend admin control panel.
- AutoTweet NG Latest Module (commercial): Shows the latest AutoTweet messages from log or the jobs in AutoTweet message queue in the admin control panel
More plugins will come in the future.
All AutoTweet NG extensions can be installed/updated by the standard Joomla installation procedure. Please install first the AutoTweet NG Component and then the needed plugins. The Content-Extension and the Automator-Plugin are packaged and installed/updated automatically with the main component. Also in most cases all installed plugins are upgraded automatically if needed. All other extensions (plugins, modules) must be downloaded and installed separately.
Requirements
All AutoTweet NG extensions have the following requirements:
- PHP 5
- PHP cURL support (with ssl extension for https)
- Joomla 1.5.4+
The AutoTweet NG extension plugins have special requirements:
- All plugins needs AutoTweet NG Component (free or pro) to work.
- Some plugins need other extensions to work (e. g. AutoTweet NG Kunena needs the Kunena forum extension). Check also the requirements listed on the download page of the component, plugin or module.
AutoTweet needs access to some domains/URLs to work:
- "twitter.com" (https://api.twitter.com/ AND https://twitter.com) for posting to twitter. Note: https is needed!!!
- "facebook.com" for posting to Facebook (pro version).
- "bit.ly" or/and "is.gd" for short url service.
- "1st-movers.com" for automatic version checks (the component checks for new versions on the server).
It is possible that your provider has restricted access to one or all of this URLs or that some firewall rules conflicts with the access to this URLs. If you have problems accessing these URLs please contact your admin and/or provider/host.
New installation
You should make a backup of your files and database before you install/upgrade extensions!
- Download newest version of AutoTweed NG Component package (free or pro).
- Install AutoTweed NG Component package with the Joomla! installer (File: com_autotweet.zip). The Content-Extension and the Automator-Plugin are installed automatically meanwhile component installation. The Automator-Plugin is enabled automatically. The Content-Extension is disabled after installation to prevent accidental posts.
- Open AutoTweet NG Component in the backend and configure the component in the parameters window.
- Check the plugin options and enable the Content-Extension (if needed).
- Donwload the other AutoTweet NG Extension-Plugins you needed and install them (File: plg_autotweet[extension].zip). Go to the plugin options and do the configuration. Don't forget to enable the plugins.
Upgrade
You should make a backup of your files and database before you install/upgrade extensions!
Information about new available versions you will find also in the information window of the AutoTweet NG component in Joomla backend.
It is not necessary to uninstall old versions of the component or plugins. You can just use the Joomla! installer to upgrade!
- Check for dependencies: Sometimes you have to update also the component when updating an extension plugin (and vice versa). Information about version dependencies you can find in the change logs (download area) on 1st-movers.com.
- Download the newest version of AutoTweed NG Component package (free or pro).
- Upgrade AutoTweed NG Component package with the Joomla! installer (File: com_autotweet.zip). This is same as installing AutoTweet (Upgrade is detected and done automatically!). The Content-Extension and the Automator-Plugin are updated automatically meanwhile component installation. The Automator-Plugin is enabled automatically. The state of the Content-Extension is unchanged. Also in most cases all installed plugins are upgraded automatically if needed.
- Open AutoTweet NG Component in the backend and check the configuration in the parameters window. (Sometimes there are new or changed options.)
- Do the same procedure for other plugins when upgrade is needed and not done automatically with the component. Sometimes plugins are disabled after the upgrade to prevent accidental posts. So you have to enable it manually!
- Check the options of all upgraded plugin.
- Open AutoTweet NG Component in the backend and check the version information in the information tab.
This procedure works also when you upgrade from free to Pro version!
Sometimes you will have problems/error message with file permissions. In this case contact your admin or uninstall the old version before installing the new. When you do this, it is NOT necessary to remove the AutoTweet database tables (manually)!
Uninstallation
Why uninstalling this amazing component? ;-)
If you uninstall the AutoTweet component with the Joomla! installer, all parts of AutoTweet (component, plugins, modules, files, database tables) are removed automatically from your system.
For all configuration options you will get some help if you move the mouse pointer over the field title.
AutoTweet NG Component
Select (in admin backend) the AutoTweet NG Component (Components/AutoTweet) and open the parameters window.
- URL handling: The article URL can be showed at the beginning or end of the twitter status message.
- Automatic resend attempts: AutoTweet resends the status message automatically if there is an error on api site. Here you can change the number of resend attempts. Change this parameter only if you have problems sending to twitter (increase attempts) or with the performance of your site (decrease attempts).
- Message/Database cleanup: The automatic cleanup function removes all messages older than the specified number of days. If you will archive your messages, you can disable this function!
- Short URLs: Disable this service ONLY, if you have problems with the short URLs (broken links, problems accessing the article from message link...) If you will use the service from bit.ly you need an account there and you can see your statistics at bit.ly (Note: You must enter your API Key in the second field, NOT your password!). You can also set 'Use always short URLs' to yes. If you do so, short URLs are used also when not needed for message lenght. This makes sense when you use bit.ly and you will have complete statistics there.
- Version checks: If you have problems or warnings on AutoTweet NG Information site (in backend), you can disable version checking and the file autotweet.ini will no longer loaded from the 1st-movers.com server (Of course you will not get information about new versions if this option is disabled).
- Overwrite base url: If set to Yes, the entered base url overwrites the url returned by Joomla for the links in all posted messages. (In some cases Joomla does not return the correct base url to AutoTweet or the IP address is returned, or https instead http. In this cases you can specify the correct base url here.) Be carefully with this and do not forget to change this when you change your site url
- Debugging and test (use this only for test purposes): If debugging mode is enabled, you will get notifications messages and returned codes when messages are queued, stored or send. The debug info is shown on top of the page.
AutoTweet NG Automator-Plugin
All messages are queued and posted by this plugin. The Automator-Plugin MUST be installed and enabled (and you need a little bit traffic on your site to trigger the plugin)!
- Max. nr of posts: Max. number of pending posts sendet by the Automator-Plugin in one time/call. (Max. 5 posts for performance reasons.)
- Interval in seconds: Interval for the post attempts of the Automator-Plugin. This means the plugin checks all X seconds for new pending posts. Min. is 120 seconds for performance reasons.
AutoTweet NG Extension-Plugins
The Extension-Plugins has similar configuration options (not each option is available for each plugin):
- Autopublish: If autobublish is disabled, messages generated by this plugin must be approved in AutoTweet backend message log before they are posted.
- Sections/Categories to post for: Select Sections/Categories which will be source of articles. The field conditions are connected by OR! (If nothing is set, all articles will be posted!).
- Excluded Sections/Categories: Specify exclusions for article posting. Exclusions has priority over all other settings! (If fields are empty, nothing is excluded).
- Post private: You can post private articles. Off course users has to login to read the linked article.
- Post modified: You can post also modified (edited) articles.
- Show section/category: You can show the section and/or category at the beginning of the message and you can selected, if you will add a '#' for hashtag support in front of category/section name. Hashtags are not supported for all channels.
- Use title or text: If your titles are not good for posting to twitter you can also use the first X chars from the article text. Enter the number of chars (from title or text) for use with message.
- Additional text/hashtags: AutoTweet can insert metakey data automatically as hashtags in the message (If no metakey data is available, AutoTweet uses also the static text if entered). Also you can use only a static text. Hashtags are not supported by all channels (e.g. Facebook ignores hashtags).
- Post replys: If this option is set to Yes also replys to articles/posts are posted.
- Post only for usertype: Send only articles posted by a specific type of user (registered users, admis/moderators).
Some plugins may have more, less or different options. Move the mouse pointer over the field title in the plugin options to get more information about options.
General: Add new channels
A channel is an account (Twitter account, Facebook account, ...) you will post messages to. In the pro version there is no limit and you can create as many as you want (Of course each post needs time and you should also thinking about the site performance when you create new channels). At the moment Twitter and Facebook is supported as channel types. More types will come up in the future.
Creating a new channel:
- Go to the tab 'Channels' in AutoTweet backend and push the 'New' button.
- Channel type: Select the channel type.
- Publish: You can publish the channel or you can do this later.
- Autopublish: If you set this to 'No', you must approve all messages for this channel before they are posting.
- Name: Enter a name for the channel.
- Description: If you will, you can enter a description for the channel.
- Channel specific account data: Some needed data is specific for each type of channel (account name, password, token, key, ...). See the next chapters for information about this.
AutoTweet NG Pro uses OAuth authentication method for Twitter access.
Authorize application and grant permissions
To activate AutoTweet for Twitter, you must authorize the AutoTweet Connector application and grant read/write permission:
- Click on the button Authorize application and grant permissions in the channel dialog.
- Click the link Authorize application and grant read/write permission for AutoTweet on the AutoTweet NG Connector site.
- Enter your Twitter account data in the Twitter dialog and press the Allow button.
- Now you are redirected to the AutoTweet NG Connector site where some additional information (token data) is displayed.
- Enter (copy/paste) the displayed token and token secret data in the corresponding fields in the channel dialog.
You can post to a personal profile, to a Facebook (business/fan) page or to a Facebook group. If you will post to a page or group, you must also enter the Facebook page or group id.
To activate AutoTweet for Facebook, you have to add the AutoTweet Connector application to your Facebook account.
Authorize application and grant the extended permissions
When you will use the Facebook support (only available in the Pro version) then you must authorize the AutoTweet application on Facebook and grant the extended permission publish_stream and offline_access to the application:
- Click on the button Authorize application and grant permissions in the channel dialog.
- Login to Facebook, authorize the application and grant the requested permissions.
- Read and check the information/instructions on the AutoTweet Facebook canvas site.
- If you will post to a Facebook page you must also grant the extended permissions for the page. Follow the instructions on the AutoTweet Facebook canvas site, click on Grant extended permissions for Facebook page and grant the requested permissions for the page.
- Enter (copy/paste) the displayed Facebook user id and - if you will post to a page or group - the displayed page or group id in the corresponding fields in the channel dialog.
Sometimes Facebook/Twitter needs time to synchronize the servers. If you get errors after authorizing, wait a little bit (maybe 1 hour) and try again.
In the pro version there is also an option to use your own app/api key to show your own branding instead the AutoTweet logo/text (not available for all channels). If you will use this feature I suggest that you know what you do. How to create an app on Facebook or Twitter is not part of this document! You must enable the option 'Use own app/api' and enter the needed data (api key and secret). After entering the data you can use the normal AutoTweet activation/authorization process by clicking on the button Authorize application and grant read/write permission for AutoTweet.
If you will use your own Twitter or Facebook app/api you must pay attention to some special requirements when creating the app:
Use AutoTweet with your own Twitter App
Create your own app on Twitter: Login to your account, go to Settings/Connections, click on "Developers can edit the registration settings for their applications here", click on "Register a new application", upload your image and enter the data. More information about Twitter Apps you will find on the Twitter developers site.
When creating your own Twitter App, please set the following parameters as described:
- Application Type: Browser
- Callback URL: http://www.1st-movers.com/twitter/autotweet/autotweet_twitter.php
- Default Access type: Read & Write
- Use Twitter for login: No (do not check the box)
After creating the App do not forget to enable the option 'Use own app/api' and enter the api key (Consumer key) and secret (Consumer secret) in the AutoTweet channel dialog. You will find this data on the information site of your App on Twitter. Finally use the normal AutoTweet activation/authorization process by clicking on the button Authorize application and grant read/write permission for AutoTweet.
Use AutoTweet with your own Facebook App
Create your own app on Facebook: Login to your account, go to the applications section, add the Facebook Developer application, click on "Create new application" within the developer application, enter a name for the app and accept the terms and conditions, upload your image and enter the general data . More information about Facebook Apps you will find on the Facebook developers wiki and the Developer Guide.
When creating your own Facebook App, please set the following parameters as described:
- Installable to: User and Facebook page (if you will use for a page)
- Canvas Callback URL: http://www.1st-movers.com/facebook/autotweet/autotweet_canvas.php? (Do NOT forget the "?"!!!) Sometimes it is neccessary to set this URL also for the Connect URL.
- Canvas Page URL: http://apps.facebook.com/[YOURAPPCANVASNAME]/ (You must enter this URL also in the AutoTweet channel dialog.)
- Canvas Render Method: FBML
After creating the App do not forget to enable the option 'Use own app/api' and enter the api key and secret in the AutoTweet channel dialog. For Facebook you must also enter the complete Canvas Page URL. You will find this data on the General tab of your App options on Facebook. Finally use the normal AutoTweet activation/authorization process by clicking on the button Authorize application and grant read/write permission for AutoTweet.
The Extension-Plugins works quietly in the background. For the usage of the backend component I will give you some hints:
Tabs
There are 4 tabs in the AutoTweet backend:
- Message Log: All logged messages are showed in this tab. For each message and posted channel there is an entry. A message is logged when a posting attempt for the queued message is done. A logged message can have the states 'error','success' or 'approve'. A message has state 'approve' when autopublishing for the source plugin or the channel is disabled. You can approve/resend messages with state 'approve' or 'error' by clicking on the state or by selecting the messages and use the 'publish' button. You can also resend messages with state 'success' by selecting the messages and use the 'publish' button and there is a function to 'approve all' messages in one step. You can delete messages the same way by using the 'delete' button. You can sort the table by clicking on the field names in the head of the table. In the row 'URL' you can see the unshorted URL for the post.
- Job Queue: All queued messages are showed in this tab. The Automator-Plugin takes the messages form this list and posts them. Also here are listed the pending messages (maybe for a longer time). This messages are waiting for posting. In most cases they has a present/future publish date.
- Channels: All created channels are listed in this tab. You can edit, delete, publish or unpublish them (Messages are send to published channels only). Also you can create new channels. In the row 'State' you will find the result of an (actual) check of the account state.
- Info: Here you will find some information about installed and available new versions.
- Facebook and Twitter uses rate limiting to avoid denial of service attacks and spam. So AutoTweet sometimes is affected by the api rate limits. See this FAQ entry for information.
|
