Munchkin JavaScript API Calls

Version 2
    Please ensure that you have access to an experienced JavaScript developer.  Marketo Technical Support is not set up to assist with troubleshooting custom JavaScript.


    The Munchkin Javascript API allows you to integrate a third-party web system with your Marketo Account. With some web development, you can capture new leads or update current leads with existing applications on your web site.


    Let's say you have a web application for customer registration that captures new customer information. With just a bit of programming, you can also have lead information for those users captured in Marketo, and a Marketo cookie set for future web tracking. In addition, another feature allows your web developers to capture and track web activity information from rich web environments such as Flash or Ajax.

    If you have the appropriate development resources, you should consider using our SOAP API for integration instead of this API. The SOAP API is more robust and has more functionality than the Munchkin API.


    Marketo SOAP API


    Requirements


    You must include the Munchkin Javascript code on your web page for any of this to work. You can find the needed script tags in the Munchkin Tutorial. You must also enable the Munchkin API, which is also described in the Tutorial.


    Under the Hood

    • After you make a Munchkin API call, it automatically cookies the user if they don't have a cookie
    • In Marketo, it logs the event (click link, visit web page, or new lead) in the person's Activity Log
    • If you're using the click link or visit web page call, the event will get added to that lead's Activity Log (known or anonymous)
    • If this is a new lead and you use the associate lead call, that lead will become a known lead and their activity history will be preserved
    • If this is an existing lead (based on email address match), any changed or new values will get updated in that lead's record


    Calling Munchkin API Functions

    Here's the general form of a munchkinFunction call.  Include it between <script> tags in your web page wherever you want to call it.
    You can invoke this like any other Javascript function. However, you must call the Munchkin tracking function mktoMunchkin() before making any mktoMunchkinFunction() calls:


    <script src="http://munchkin.marketo.net/munchkin.js" type="text/javascript"></script>
    <script>
      mktoMunchkin("###-###-###");
      mktoMunchkinFunction('function',
                           { key: 'value', key2: 'value'},
                           'hash');
    </script>


    where:

    • ###-###-### is the Munchkin account ID for your account
    • function is the call you want to make
    • params is an array of parameters needed for the call
    • hash is only needed for associateLead

     

    Visit Web Page

    Use this call to record that the user did something, like visit a page in Ajax, Flash, or other RIA environment. The URL must not contain " or any domain, but it can point to any page -- even pages that don't exist. If you want to add URL parameters, use the params argument.

    The event shows up as a Visit Web Page event in the user's activity log under the domain of the calling web page.


    Your first call to mktoMunchkin() always creates a Visit Web Page event for the current page. You do not need to call visitWebPage unless you want to track an additional web page visit.

     

    mktoMunchkinFunction('visitWebPage', {
        url: '/MyFlashMovie/Story1', params: 'x=y&2=3'
    });

     

    Click Link

    This call records a 'Click Link' event in the user's activity log. Use this when you want to record that a user clicked an Ajax, Flash, or other RIA link.

     

    The href can be any value -- even a page that doesn't exist -- but the href must not contain ", domains, or URL parameters. The click link event will have the domain of the calling web page.

     

    mktoMunchkinFunction('clickLink', {
        href: '/MyFlashMovie/Story1'}
    );

     

    Associate Lead

    Use this function to create a new lead in Marketo or associate the user with an existing lead.  This is ideal if you have your own forms that you don't want to edit. Likewise, this is great if you have a login system and want to identify people on your website.

     

    Do not use the AssociateLead call with Web2Lead forms; that will duplicate leads in Marketo and Salesforce.  You must replace those with Marketo forms (which eliminates the need for this API call) or your own forms on your website (with this API call).

     

    You must include the email address. Marketo will automatically de-duplicate the lead if one already exists in your database. In that case, any new or updated values you provide in the call will get updated for that lead.


    If it was previously an anonymous lead, the lead will become known after you make this call (provided you supply the name and email address).

     

    The call has 2 parts. First, there's an array of field name and value pairs. These field names come from Marketo.

     

    The examples below include common fields you might use. To get the API names for the fields, go to the Field Management page of the Admin section.  Then click the Export Fields button.  The API field names will be in that spreadsheet.

     

    Field Management.png

    The second part is a security hash, encoded with SHA1.  To generate this, concatenate your API Private Key with the lead's email address, then encode it with SHA1 (the non-HMAC version).  Make sure it's in lowercase so it gets processed correctly.

     

    Do not calculate the SHA1 hash in Javascript; it must be calculated on your server.  Putting your private key in the HTML of the page is insecure and may allow others to make modifications to your Marketo account.


    You should use this call on the page following a form submit for a login, information request, or registration.  On that following page, make the munchkinFunction call like this (in PHP).

     

    mktoMunchkinFunction(
       'associateLead',
       {
          Email: <?php echo "decodeURIComponent(\"" . rawurlencode($_REQUEST["email"]) . "\")" ?>,
          FirstName: <?php echo "decodeURIComponent(\"" . rawurlencode($_REQUEST["first_name"]) . "\")" ?>,
          LastName: <?php echo "decodeURIComponent(\"" . rawurlencode($_REQUEST["last_name"]) . "\")" ?>
       },
       '<?php echo hash('sha1', 'my-secret-key' . $_REQUEST["email"]); ?>'
    );

     

    Here's an example of a fully fleshed out API call, again with PHP.

     

    mktoMunchkinFunction('associateLead',
                    {
                       // Lead Attributes
                     DateofBirth: '1985-05-15',
                     Description: 'I want to buy',
                       DoNotCall: true,
                 DoNotCallReason: 'just because',
                    Email: 'person@company.com',
                             Fax: '111-222-3333',
                       FirstName: 'Dave',
                        LastName: 'Smith',
                      MiddleName: 'Bruce',
                     MobilePhone: '222-333-4444',
                           Phone: '333-444-5555',
                      Salutation: 'Mr.',
                           Title: 'CEO',
                    Unsubscribed: true,
                        LeadRole: 'Buyer',
                       LeadScore: 15,
                      LeadSource: 'Purchased List',
                      LeadStatus: 'Open - Not Contacted',
                          Rating: 'Warm',

     

                       // Company Attributes
                   AnnualRevenue: 123456,
                            City: 'St. Louis',
                         Company: 'Widgets',
                    CompanyNotes: 'Just sold!',
                         Country: 'U.S.A.',
                        Industry: 'Manufacturing',
                       MainPhone: '314-234-0242',
               NumberOfEmployees: 52523,
                      PostalCode: 63141,
                         SICCode: 'ABC-2114',
                            Site: 'headquarters',
                           State: 'MO',
                          Street: '1 Main',
                         Website: 'www.widgets.com',
                        
                       // Custom Attribute
                        Level__c: 'Tertiary'
                    },
                    'echo hash('sha1',
                               'my-secret-key!' . 'person@company.com'); ?>');

     

    ASP Example (not .NET)

    Here's an ASP example from Francois St-Maurice of Ortivus.

     

    This script assumes that the sha1.wsc file is located in the "/include/" directory of your website. You can download this file here:

     

    http://uwblog.googlecode.com/svn/trunk/includes/sha1.wsc

     

    Here's a more detailed explanation of the sha1 encryption module:

     

    http://precompiled.wordpress.com/2007/11/26/hmac-sha1-encryptie-onder-classic-asp/
    (The links in the article are incorrect, but a comment near the end of the page gives correct links.)

     

    <%
            Dim sha1
            set sha1 = GetObject("script:" &
            Server.MapPath("/include/sha1.wsc"))

     

               ' set the resulting hash in upper case
            sha1.hexcase = 1

     

            Dim encryptedEmailResult

     

               ' get the sha1 encryption result
            encryptedEmailResult = sha1.hex_sha1(
                 "my-secret-key" & Request.Form("EmailField"))
    %>

     

    <script type="text/javascript">
       function MarketoUpdate() {
         mktoMunchkinFunction ('associateLead',{
           Email:'<%=Request.Form("EmailField")%>',
           FirstName:'<%=Request.Form("FirstNameField")%>',
           LastName:'<%=Request.Form("LastNameField")%>',
           Street:'<%=Request.Form("StreetField")%>'},
          '<%=encryptedEmailResult%>');
       }
    </script>

     

    Generating the key with .NET

    Here is a function for generating the SHA1 key using native .NET calls, provided by George Vaccaro:

        string GetEncryptedEmail(string emailAddress) {
        string encryptedEmail = "";

     

        string apiKeyEmail = apiKey + emailAddress;
        byte[] input = Encoding.UTF8.GetBytes(apiKeyEmail);
        byte[] hash = null;

     

        SHA1 sha = new SHA1CryptoServiceProvider();
        hash = sha.ComputeHash(input);
        encryptedEmail = BitConverter.ToString(hash).Replace("-", "");

     

        return encryptedEmail.ToLower();
      }

     

    Tracking Anonymous Leads and Fixing Forms

    By default, Marketo software tracks anonymous leads. Anonymous leads are leads where the user has visited your web site, but has not been identified by filling in a form, clicking a link in an email, or by the associateLead function being used to tie the user to a customer record.

     

    You can turn off the generation of cookies for anonymous leads on a given page by adding the following code to your Munchkin call:

     

    cookieAnon: false

     

    With this code in place, an event will be generated when a previously cookied user visits your web page. However, a new cookie will not be placed, and no event will be generated, if the user has not previously received a cookie.

     

    When you turn off tracking anonymous leads, you have an option for how to handle forms on the page. Marketo can "fix" any form on the page that does not have a dynamically added "submit" handler.

     

    Munchkin will chain in a handler that will create a tracking cookie, generate a visit web page, then call any onsubmit handler. The onsubmit handler has to have been specified using the <form onsubmit=""> attribute. If no onsubmit handler has been specified, Munchkin calls form.submit.

     

    To turn off this activity, add the following attribute and value to your Munchkin call:

     

    trackAnonFormFix: false

     

    Override the trackAnon Setting

    Marketo software creates and stores the Munchkin tracking cookie, named _mkto_trk, in most cases where it is not already present. However, if cookieAnon is set to false (see the previous section), the cookie will not normally be created and stored for anonymous leads.

     

    To force the creation of the Munchkin tracking cookie, use the following call:

     

    createTrackingCookie (forceCreate: true)

     

    The createTrackingCookie function is usually superfluous - however, if forceCreate is set to true, it creates a cookie even when cookieAnon is set to false. This is useful when cookieAnon is set to false and the user is submitting a form, posting to a server to do a SOAP API syncLead, and so on - actions that make the lead known, rather than anonymous, and the cookie has to be created before the next GET or POST to the server.

     

    Marketo software also generates a Web page tracking event and sends it to the server to register a Web page visit, except when cookieAnon is set to false. To override cookieAnon when it's set to false, and force the event to be generated and sent to the server, use the following call:

     

    generateVisitWebPage ()

     

    Changing the Click Link Delay

    When a link is clicked, or a Web page visit has been completed, Munchkin delays before completing the action (sending through the link click or posting a form). The default delay is 200 milliseconds.

     

    If you have tracking or Web page performance problems, you may wish to change the delay.

     

    To change the delay, add the following attribute to your Munchkin call:

     

    postWait ms ###

     

    Replace ### with the delay you wish to use; the default value is 200.

    Triggering Campaigns with Munchkin API

    If you want to trigger a campaign when a new lead is created via the Munchkin API, use the Lead is Created trigger with a constraint on "Source Type is Munchkin API" like this:

     

    Lead is Created.png

     

    To trigger campaigns on other web events, you can use the Visit Web Page with a URL parameter. For example, say you have a web page with a flash video. When the lead watches the video, you can use Actionscript to call this Javascript:

     

    mktoMunchkinFunction('visitWebPage', {

         url: document.location.path, params: 'playedVideo=true'

    });

     

    Then you can use this triggered campaign to change the lead score, alert your sales reps, or take any other flow actions:

     

    Visits Web Page.png