The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-Myspace-FriendAdder-0.16
++
/ WWW::Myspace::FriendAdder

NAME

WWW::Myspace::FriendAdder - Interactively add friends to your Myspace account

VERSION

Version 0.15

WARNING

March 2007: Using WWW::Myspace for commenting, messaging, or adding friends will probably get your Myspace account deleted or disabled.

SYNOPSIS

This module gives you a little more flexibility when adding friends to your Myspace account. It is interactive and will occasionally prompt you for input. You'll have the most success when using it at the command line, but you do have the option of suppressing its reporting and interactive nature if you want to run it from a cgi script or if you just find it annoying. Hey, you've got your reasons, right? This module is an extension of Grant Grueninger's handy WWW::Myspace module.

    use WWW::Myspace;
    use WWW::Myspace::FriendAdder;

    my $myspace = WWW::Myspace->new();

    my $adder = WWW::Myspace::FriendAdder->new( $myspace );

    my @friend_ids = ('List', 'of', 'friend', 'ids');

    $adder->send_friend_requests( @friend_ids );

By default, this routine will try to add as many friends as possible until it it reaches max_count, which defaults to 50, but can be set to any number of your choosing. See below. When Myspace prompts you for user input, the routine will pause and allow you as much time as you need to fill out the Myspace form. Once you have done so, you may prompt the script to continue or to exit. Upon its exit, the script will report on its success and/or failure.

CONSTRUCTOR AND STARTUP

new()

Initialize and return a new WWW::Myspace::FriendAdder object. $myspace is a WWW::Myspace object.

Example

    use WWW::Myspace;

    use WWW::Myspace::FriendAdder;
    
    # see WWW::Myspace docs for more info on user/pass usage
    my $myspace = WWW::Myspace->new(); 

    my $adder = WWW::Myspace::FriendAdder->new( $myspace );
    
    # or pass some startup parameters
    my %startup_params = (
        exclude_my_friends  => 1, 
        max_count           => 25, 
        config_file         => '/path/to/config_file.cfg',
    );
    
    my $adder = WWW::Myspace::FriendAdder->new( 
        $myspace,
        \%startup_params, 
    );

    # find all of Shania Twain's friends 
    # (hey, you've got your reasons...)
    my @friend_ids = $myspace->friends_from_profile('13866406');
    
    # now, ask Shania's friends to be your friends
    $adder->send_friend_requests( @friend_ids);

Optional Parameters

  • config_file => $value

    If you prefer to keep your startup parameters in a file, pass a valid filename to new.

    Your startup file may contain any of the parameters that can be passed to new() (except the $myspace object). Your config file will be used to set the default parameters for startup. Any other parameters which you also pass to new() will override the corresponding values in the config file. So, if you have a default setting for exclude_my_friends in your config file but also pass exclude_my_friends directly to new(), the config file value will be overriden. The default behaviour is not to look for a config file. Default file format is YAML.

        my $adder = WWW::Myspace::FriendAdder->( 
        $myspace, 
        { config_file => '/path/to/adder_config.cfg', }, 
    );

  • config_file_format => [YAML|CFG]

    If you have chosen to use a configuration file, you may state explicitly which format you are using. You may choose between YAML and Config::General. If you choose not to pass this parameter, it will default to YAML.

  • exclude_my_friends => [0|1]

    You can only perform a set number of friend requests per day. I don't know what that number is. At this point, it's more than 200, It could be as many as 300. If you know, let me know. I can't tell you for sure, so don't go crazy and try 1,000 requests in an hour. A failed request is a wasted interaction, and there's really no point in trying to add people who are already on your friends list. It just makes you look like someone who has no clue. So, if you want to get the most out of your bandwidth and CPU, set this value to be true. Currently this info is not cached, so your friend ids will have to be looked up every time you run the script. However, if you have successfully called get_data_object() (see below) your friends list will be retrieved via SQL. This is a BIG time saver if you have more than just a few friends.

  • firefox => ["/path/to/firefox/bin +options"]

    "interactive" (see below) must be switched on for the "firefox" parameter to be enabled. Previously, the preferred method for dealing with CAPTCHA requests was to print out the URL to the terminal. You'd then copy/paste the URL into your web browser, fill out the CAPTCHA request and then prompt the script to continue. Things just got (marginally) easier. I have only tested this on my Ubuntu (Edgy) machine, but it works really well. It's a bit of a hack, but really most of this module is just that.

    In order for this to run smoothly, fire up your Firefox browser *before* running your FriendAdder script. Log in to your Myspage page and then fire up the script in a terminal. Now, when the CAPTCHA request appears, the CAPTCHA URL will automatically be loaded by Firefox. Just switch over to Firefox, fill out the CAPTCHA request and then prompt the script to continue. It cuts out one step in the process, but I've found it to be very handy.

    For example, in your script:

      Create your $myspace object like this:

      # Enter *exactly* the same UserAgent as the browser you'll be using

      my $user_agent = 'Mozilla/5.0...';

      my $myspace = WWW::Myspace->new ( auto_login => 0, account_name => 'your@email.com', password => 'seekrit', );

      $myspace->mech_params({ agent => $user_agent, });

      $myspace->_new_mech;

      $myspace->site_login;

      # set up your startup params

      my %params = ( ... # whatever your params would otherwise be firefox => "/usr/bin/firefox -new-tab ", );

      # create a new FriendAdder object

      my $adder = WWW::Myspace::FriendAdder->new($myspace, \%params);

    The advantage of doing things this way is that your $myspace UserAgent and your browser's reported UserAgent will be identical. You can now let the script run in a terminal window and come back to it every so often to deal with a CAPTCHA request.

    Note that I've passed the "new-tab" option to the binary. This tells Firefox to (naturally) open a new tab in an existing browser instance. You can try other options if you like. Just make sure you're already logged in via your browser or you'll be kicked to a login page rather than the CAPTCHA page and that sort of defeats the whole purpose of the exercise.

    If you get this to work on a non-Linux platform, please let me know how to do it so I can add it to the docs.

  • interactive => [0|1]

    This module is at its most powerful when you are able to interact with it. If you don't feel like interacting, set this to 0. Default is on.

  • last_login => days

    It doesn't always make sense to send an add request to someone who hasn't logged in to their account in ages. last_login is a value, in days, which will force FriendAdder to skip anyone who hasn't logged in over the last last_login days. So, passing last_login => 60 will mean that you don't waste add requests on folks who haven't logged in over the last 2 months. They've probably moved on to something better by now...

    This parameter defaults to 0, which is off. Keep in mind that if you're using Data.pm this could add the overhead of an extra page load for each attempted friend request. If you want to keep your Myspace calls to a minimum, you'll want to keep this disabled.

  • max_count => $value

    Set this to any positive integer and FriendAdder will stop friend requests when it reaches this upper limit. Default is 50.

  • profile_type => [ 'band' | 'personal' | 'all' ]

    Set this to band if you only want to add bands. Set it to personal if you only want to add personal pages. Defaults to "all" (adds any profile).

  • random_sleep => [0|1]

    Want your script to feel more human? Set random_sleep to 1 and send_friend_requests() will take random breaks between add requests using Perl's built-in rand() function. The upper limit of the random number will be set by the sleep option (see below). Default is off.

  • sleep => $seconds

    Myspace's network connectivity is wonky at the best of times. Best not to send a request every 0.1 seconds. Set this to any positive number and send_friend_requests() will sleep for this many seconds between add requests. If you enable random_sleep (see above), this number will be the upper limit of the random sleep time. Default is 10.

  • sleep_on_captcha => $seconds

    CAPTCHAs will go away if you wait long enough. If you're running a cron or a background process, you may want to let the script sleep and then check back in. A suggested time would be just over 12 hours or something greater than 33,200 seconds. You should note that this *will* kick in *before* the firefox param is checked, so if you're not sure you'd like to wait several hours when you hit CAPTCHA, this is not for you. Default is off.

send_friend_requests( @friend_ids )

This method is the main force behind this module. Pass it a list of friend_ids and it will try to add them to your friends. This method is really just a wrapper around $myspace->send_friend_requests() It adds interactivity and advanced reporting to the WWW::Myspace method. You'll get most of the info that you need printed to your terminal when you run your script from the command line. But, the script will also return a hash reference which you can use to create your own reports. The hash is keyed on response codes returned by WWW::Myspace. The value of each key is a list of friend ids which returned with that status code.

    my $report = $adder->send_friend_requests( @friend_ids );
    
    # when run at the command line, you may see something like this:
    
    $ perl add.pl 

    Beginning to process the ids...
    1)      9395579:        Failed, this person is already your friend.
(FF)
                            Sleeping for 4.95 seconds...
    2)      9373522:        Passed! Verification string received. (P)
                            Sleeping for 2.43 seconds...
    3)      9315640:        Failed, you already have a pending friend
request
                            for this person (FP)
                            Sleeping for 5.71 seconds...
    4)      9277516:        Passed! Verification string received. (P)
                            Sleeping for 1.78 seconds...
    5)      9269809:        Passed! Verification string received. (P) 
    
    Max attempts (5) reached. Exiting nicely...
    
    Final status report...
    
    ######################
    5 successful adds
    1 Failed, this person is already your friend. (FF)
    1 Failed, you already have a pending friend request for this person
(FP)
    3 Passed! Verification string received. (P)

    # %report may look something like this...
    my %{$report} = (
        'FF' => [
                    '9395579'
                ],
        'FP' => [
                    '9315640'
                ],
        'P' => [
                   '9373522',
                   '9277516',
                   '9269809'
                 ],
        );

add_to_friends( @friend_ids)

Convenience method - same as send_friend_requests.

is_band()

If a WWW::Myspace::Data object exists, returns the value of $data->is_band Otherwise, returns the value of $myspace->is_band

return_params( )

Useful for testing whether your params have been set as expected.

    my $param_ref = $adder->return_params();

get_data_object( )

Returns a valid WWW::Myspace::Data object if one can be initialized by the WWW::Myspace::FriendAdder object. This method will croak if no object can be created. This is a handy shortcut if you're using WWW::Myspace::Data in conjunction with FriendAdder.pm but don't want to go to the trouble of creating the WWW::Myspace::Data object yourself. Just remember to install WWW::Myspace::Data first.

    my $data = $adder->get_data_object();
    if ( $data ) {
        my @friends = $data->friends_from_profile(...);
    }

_report( )

Internal method. If the interactive switch is on, this will print. If it's not, well you can probably guess.

_sleep_now( )

Internal method that handles sleeping between requests.

_die_pretty( )

Internal method that deletes the Myspace object from $self and then prints $self via Data::Dumper. The Myspace object is so big, that when you get it out of the way it can be easier to debug set parameters.

    $adder->_die_pretty;

AUTHOR

Olaf Alders, <olaf at wundersolutions.com> inspired by the excellent code of Grant Grueninger

BUGS

Please report any bugs or feature requests to bug-www-myspace-friendadder at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Myspace-FriendAdder. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

NOTES

This module has been stable for some time. Myspace, however, is not. I've written this code to suit my own needs. If it does not suit all of yours, patches are very welcome.

HOW TO SUBMIT A PATCH

Please see the HOW TO SUBMIT A PATCH section of WWW::Myspace for a quick set of instructions on how to get your patch included in a coming distribution.

TO DO

Right now the adder won't deal with FU CAPTCHA pages. That's fine for my purposes, so if you need that functionality, please open a ticket.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::Myspace::FriendAdder

You can also look for information at:

ACKNOWLEDGEMENTS

Many thanks to Grant Grueninger for giving birth to WWW::Myspace and for his help and advice in the development of this module.

Thanks to Jason A. Ramsey (jason AT eramsey.org) for his contribution of the sleep_on_captcha code: http://rt.cpan.org/Ticket/Display.html?id=19808

COPYRIGHT & LICENSE

Copyright 2006-2007 Olaf Alders, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.