Why customize?

Guguchu offers an easy way to set up a full-featured customizable band page without the need to edit HTML or Javascript. When joining Guguchu, you'll have a complete band website customizable with your own background images, banner and color schemes, and displaying your discography, show list, music store, ticket sales, bio, and more.

band page
Full-featured band page

We believe that in some cases you'll need more (or less) and require more granular customization.

Traditionally, custom website integration is done by sticking in flash widgets, which works well in many scenarios, but is also limited by a "boxy" look-and-feel.

If you prefer having your own band website, blog, release page or other online fan or customer destination, but need a secure streaming infrastructure or music store, you can now use our Javascript APIs and embed those features seamlessly.

Audience

There are two ways to use the Javascript API when integrating Guguchu functionality into custom websites:

  1. HTML class names: Simply add specific class names and attributes to your template. You don't need to write any Javascript code for this. This approach is simple and non-obtrusive.
  2. Javascript API: Two "classes" are provided. GuguchuPlayer and GuguchuStore. They export methods and register events, which can be used to write fully customized UIs.

Examples

Basic Usage

The following bare-bone example shows the use of guguchu-* class names when attaching functionality to a basic HTML template. The API is included and initialized inside the head tag.

<html>
<head>

...

<!-- Guguchu Javascript API -->
<script type="text/javascript" charset="utf-8" 
    src="http://assets.guguchu.com/api/v1.0/all.js"></script>
    
<script type="text/javascript" charset="utf-8">
    // Initialize the API with your band url. 
    // For instance guguchu.com/code would be:
    guguchuApi.init("code"); 
</script>

</head>
<body>

<!-- add a play and stop button -->
<a class="guguchu-player-play" href="#839-3974">[Play]</a>
<a class="guguchu-player-stop" href="#">[Stop]</a>

<!-- and a buy button for the album -->
<a class="guguchu-store-buy" href="#0fe6a94848e5c68a54010b61b3e94b0e">[Buy]</a>

</body>
</html>

Note that the "a" tags use the "href" attribute to refer to the track/product to be played or purchased respectively. You can obtain the these IDs for each of your albums, songs and tickets in your Guguchu Manager under Products => embed.

Try it out:
[Play] [Stop] [Buy]
More advanced integration

The following example shows how to call the player controls directly and register event handlers to create a custom album mashup.

<html>
<head>

...

<!-- Guguchu Javascript API -->
<script type="text/javascript" charset="utf-8" 
    src="http://assets.guguchu.com/api/v1.0/all.js"></script>

<script type="text/javascript" charset="utf-8">

    // inititalize after API has finished loading
    guguchuApi.init("code", function(){  

        // Attach click events to track list
        $(".mashup .tracklist li").click(function(){
            if ($(this).hasClass("playing")) {
                // stop if already playing
                $(this).removeClass("playing");
                guguchuPlayer.controls.stop();
            } else {
                // play/switch track
                var track = $(this).attr("id").substr(6).split("-");
                $(".mashup .tracklist li").removeClass("playing");
                $(this).addClass("playing");
                guguchuPlayer.controls.play(track[0], track[1]);
                return false;
            }
        });
        
        // Handle track change events to change "playing" class
        $(".mashup .tracklist").bind("trackChanged", 
            function(e, oldTrack, newTrack){
                $("li", this).removeClass("playing");
                $("#track-"+newTrack.listId+"-"+newTrack.id).addClass("playing");
            }
        ); 
</script>

</head>
<body>
...

<div class="mashup">
    <div class="buy">
        <a class="button black guguchu-store-buy" 
            href="#0fe6a94848e5c68a54010b61b3e94b0e">Buy Now</a>
    </div>
    <ol class="tracklist">
       <li id="track-839-3976">No Bliss (Geedel remix) - 04:15</li>
       <li id="track-839-3975">EQ (Geedel remix) radio edit - 04:32</li>
       <li id="track-839-3974">EQ (Geedel remix) extended - 07:06</li>
    </ol>
</div>
...
</body>
</html>

Try it out:
Buy Now
  1. No Bliss (Geedel remix) - 04:15
  2. EQ (Geedel remix) radio edit - 04:32
  3. EQ (Geedel remix) extended - 07:06

Reference

Initialization

The Guguchu API loads its modules asynchronously from our delivery network to ensure your site can load smoothly. If you call player or store controls directly, you should do so inside the initialization callback. 

<!-- Guguchu Javascript API -->
<script type="text/javascript" charset="utf-8" 
    src="http://assets.guguchu.com/api/v1.0/all.js"></script>
    
<script type="text/javascript" charset="utf-8">
    
    function myInit() {
        // do your custom initialization here...
    }
    guguchuApi.init("<your_band>", myInit); 
</script>

GuguchuPlayer methods

Set out below are the player methods that are currently available together with their alternative class names, which can be applied to "a" tags. The class name approach provides a non-obtrusive alternative for situations when calling Javascript methods is not desired or necessary. The classes are bound as live events, meaning they will work even if you create the element dynamically after the DOM has finished loading.

function guguchuPlayer.controls.play(trackToken) Class: guguchu-player-play Attribute: href="#trackToken" Start playing a track. If the track is already playing, it will rewind and start over.
trackToken is the token formatted "listId-trackId" obtained from the embed section in the Guguchu Manager.
function guguchuPlayer.controls.play(listId, trackId) Class: guguchu-player-play Attribute: href="#trackToken" Same as above but listId and trackId as separate arguments.
function guguchuPlayer.controls.pause() Class: guguchu-player-pause Pause the current track. Ignored if nothing is playing.
function guguchuPlayer.controls.resume() Class: guguchu-player-resume Resumes the currently paused track at its last position.
function guguchuPlayer.controls.next() Class: guguchu-player-next Skips to the next track in the playlist the track belongs to. It follows the order specified when the album was created. If the end of the list has been reached, this call is ignored.
function guguchuPlayer.controls.prev() Class: guguchu-player-prev Returns to the previous track in the playlist the track belongs to. It follows the order specified when the album was created. If the current track is the first in the list, this call is ignored.
function guguchuPlayer.controls.stop() Class: guguchu-player-stop Stops the player and resets playing position.
function guguchuPlayer.controls.seek(pos) Class: not available If a track is currently playing, jump to time position pos (in milliseconds).
You'll get the total length from the trackChanged event (see below).

GuguchuPlayer events

To have your UI update when the player changes state, you can bind one or more of the following events. Examples above use jQuery's method, but other ways should work as well. Note that the events are global and don't need to be bound to any specific DOM element.

event: "trackChanged" callback: function(e, oldTrack, newTrack) Triggered when the player changes the currently playing track. oldTrack is null if the first track is started.
The track object has the following read-only properties: 
Track.id - the track's id
Track.listId - the playlist id
Track.artist - artist name
Track.album - the album or playlist name
Track.title - the track's title
Track.length - length of the track in milliseconds

event: "trackProgress" callback: function(e, track, pos) Triggered repetitively as a track is playing and the play head advances.
track - the current track
pos - the current position in milliseconds

GuguchuStore Methods

The Guguchu Store API works very similar to the player API, but is much simpler. You can call the API directly or use the alternative class names to create "buy buttons". There are no events in the Store API.

function guguchuStore.addItem(productId) Class: guguchu-store-buy Attribute: href="#productId" Adds the product with productId to the shopping cart and opens the cart's window.
productId can be obtained from the embed section in the Guguchu Manager.
function guguchuStore.freeItem(productId) Class: guguchu-store-free Attribute: href="#productId" Used for free downloads/items. Opens the email dialog.
productId can be obtained from the embed section in the Guguchu Manager.

Current limitations

The API is fully operational, but is still in beta. While it should work fine with most integration, you should be aware of the following limitations which we will remove in forthcoming releases:

Dependencies

The current version depends on jQuery, which is automatically loaded. This generates potential conflicts with other libraries such as Prototype or YUI.

Merchandize Products

In its current version, the Javascript API supports digital downloads and ticket products. As the Guguchu merch store has not been rolled out to all accounts yet, merch products are not yet supported.

Single Instance

Currently, the Guguchu API objects are a single instance and can only be used once per page and initialized with one band only. You may consider a cross-promotion with other accounts on Guguchu like, for instance, a small music store. We'll add this capability in the near future.

HTML5 audio support (WebKit-based mobile browsers)

Is currently not supported but will be included in forthcoming releases.

Feedback

To provide feedback or report problems, please use our feedback page.
We'd love to see what you come up with. If you have created something that you think is awesome, please let us know and we can showcase it on our front page.