The Flash Designer's Guide to Acrobat

Introduction:

This guide is for designers using Adobe Flash Professional who want to create SWF content that is intended to play inside PDF documents using the Flash Player in Acrobat in Adobe Acrobat 9 or higher.

One of the great new features of Adobe Acrobat 9 Pro and Pro Extended is the ability to add SWF-based Rich Media Annotations (RMAs) developed in Flash (or Flex). These SWF files can be placed in a PDF document using the new Flash Tool in Acrobat 9 and play using the Flash Player in Acrobat. The Flash Player in Acrobat provides greater security and consistency for Flash playback inside any PDF document. For those of you that attempted to use Flash in a PDF document in earlier versions of Acrobat, you’ll remember that the user experience wasn’t all that great. Acrobat 9 provides tight integration between the PDF document and the RMAs well as other content types that run in the Flash Player in Acrobat such as FLV and H.264 encoded video.

Placing Your SWF Content as a Rich Media Annotation in Acrobat

Placing a simple SWF file into a PDF document is as easy as adding it to an HTML page. However, there are a few additional settings that are important to get right in order to create the exact experience you want for your end users. The most important being the "Playback Style"

There are two ways to play the SWF in Acrobat or Reader, on the page or in a floating window.


Click to Zoom

The floating window has certain advantages when you need the SWF to be present regardless of what page you are on in the PDF file.


Click to Zoom

When the SWF is played on the page, you are able to use the Acrobat commenting features to review and markup the interactive content. More on that a little later in this article.

Tip: If you intend to play the SWF on the page, select the the Flash tool from the toolbar and double-click on the PDF page rather than dragging out a marquee. By double clicking and then selecting the SWF from the dialog box, the SWF will be placed at actual size and the rectangle for the Rich Media Annotation will be the right size.

Note: Read “Add multimedia files to a PDF” to learn how to add RMAs to PDF files using the new Flash tool rather than the legacy multimedia object.

You can either embed the SWF in the PDF document by selecting it from your hard drive or you can reference the SWF via a URL. Three types of URLs can be used: RTMP, HTTP, and HTTPS. Flash Media Servers (FMS) use RTMP to host FLV files and H.264-compliant media files. On HTTP and HTTPS servers, FLV files and H.264-compliant MOV and MP4 files are supported.

One advantage to referencing the SWF via a URL is that you can update the SWF at any time without needing to update the PDF file and then redistribute it. However, there are security restrictions associated with this approach so you may not want to use this method unless you understand the desktop environment of your users. I’ll talk more about these security restriction a little later in this article.

In the "Insert Flash" dialog you have the option of checking "Show Advanced Options". While not absolutely necessary, I always use the advanced options because I want to control the exact experience my end-users see. You’ll see three tabs where you can change the behavior of your SWF when running in the Flash Player in Acrobat.

The Launch Settings tab


Click to Zoom

Use these settings to determine how the media is started and stopped, where it is displayed, and what is displayed when the media isn’t running.

Activation Settings
Select options to determine when the media is played and stopped. From the Playback Style menu, select "Play Content In Floating Window" to have the SWF run in a window over the page. Content in a floating window enables users to read the page and interact with the SWF at the same time. The floating window will always open up in the upper right corner of the Acrobat or Reader UI, you have no control of it’s initial position however, the width and height settings allow you to specify it’s size.

Border Width
"Border Width" creates a black border around the SWF. If you are playing the SWF in a floating window you’ll need this border so that users can easily move the window around, resize it or close it.

Poster Image
The "Poster Image" allows you to specify an image that you want to be displayed when the SWF content is not activated. Acrobat will create a default "Poster Image" for you but I typically don’t find it satisfactory (though it is a very good guess at what I might want).

The Flash tab


Click to Zoom

"Pass Context Menu Click to Flash Movie" allows Flash developers to replace the Acrobat context menu with the context menu of the originating SWF file. When the user right-clicks the SWF file, the available options are from the originating file.

FlashVars work exactly the same way in Acrobat as in HTML.You can pass FlashVars through this dialog if you always need the same variables. If you need to pass FlashVars at runtime, be sure to read the section on "Communicating with Acrobat and the PDF document" later in this article.

The Resources tab


Click to Zoom

If your SWF file requires any resources that are externally referenced via relative URLs like images, style sheets or other SWFs, and you are embedding the SWF in your PDF file, use the "Resources" tab to additionally embed all of the externally referenced files that are required to run the SWF. Think of the PDF file as your server and use this tab to "upload" everything that your server would need to play the SWF.

Note: If your SWF is not functioning properly inside of Acrobat it is most likely a failure to embed all of the required resources. See the section just below, "Development Restrictions", for the next most likely reasons.

Development Restrictions

Rich Media Annotations in Acrobat and Reader use an embedded Flash Player runtime that is independent of the Adobe Flash Player installed on the system. However, not all objects allowed in SWF content playing in a network or web environment are allowed when playing inside the Flash Player in Acrobat; most significantly, SharedObjects, LocalConnection, FileReference and and user initiated sockets (though that restriction does not apply to RTMP streaming). However, there are Acrobat corollaries to the first two. If you need this sort of functionality, you’ll also want to be sure to read the section on "Communicating with Acrobat and the PDF Document" for implementation advice.

Local Shared Objects:
SharedObject is disabled in the Flash Player in Acrobat. Instead you can use a "JavaScript for Acrobat" object called "global". "Global" is a JavaScript object that allows you to share data between documents and to have data be persistent across sessions. Such data is called persistent global data. Global data-sharing and notification across documents is done through a subscription mechanism, which allows you to monitor global data variables and report their value changes across documents. Each time a global variable is written to, the origin which set it is remembered. Only origins that match can then access the variable. For files, this means only the file that set it, having the same path it had when the variable was set, can access the variable. For documents opened from URLs it means only the host which set it can access the variable.

You can use a combination of the Flash ExternalInterface Object and JavaScript for Acrobat to store and retrieve data from the global object. See the links at the end of this article to learn how.

LocalConnection:
LocalConnection
is disabled in the Flash Player in Acrobat. However, again, you can use a combination of the Flash ExternalInterface Object and JavaScript for Acrobat to communicate between SWFs running in the same PDF file. I’ve got a Flex tutorial and example here but the concepts are the same for Flash Professional.

Publishing Your SWF from Flash Professional

In your Publish Settings in Flash Player Professional, you can target Flash Player 9 and ActionScript 1, 2 or 3. Your SWF should work when used as a Rich Media Annotation. You can also target Flash Player 10 if you intend your files to be viewed in Acrobat 9.2 or higher; the equivalent of Flash Player 9 was available in Acrobat 9.0 and 9.1.

However, if you intend your SWF to be used in the Header or Welcome Page of a PDF Portfolio, you must use ActionScript 3 when you publish your SWF. These PDF Portfolio elements are "modules" of an AS3 application and won’t work properly if they are not written using AS3.

Flash Player in Acrobat Sandbox Security Model

Your SWF is allowed to use resources that were embedded during the authoring of the PDF file, but is restricted from accessing resources external to the document except to support streaming FLV files or to access trusted URLs. In all cases, a SWF running in Acrobat is subject to both Acrobat and Flash Player security rules. Acrobat provides the first layer of security features. The operation fails if Acrobat disallows the access. If it is allowed by Acrobat then it is checked against the security rules of Flash Player. The operation fails if Flash Player disallows the access. External Access is permitted only if both Acrobat and the Flash Player allow it.

If you are creating PDF files with dynamic content that is not wholly embedded in the PDF file itself, you’ll need to read this white paper and this blog entry.

Advanced Functionality Available to SWFs running in the Flash Player in Acrobat

In addition to the Flash Player in Acrobat providing greater security and consistency for SWF content playing inside of PDF files, it also has built-in functions that take advantage of features found only in Adobe Acrobat and Adobe Reader.

Saving State and Commenting

With a small amount of coding, you can keep the state of your SWF persistent in the PDF so that when the file is saved then re-opened, your SWF looks exactly the same. You can also do the same sort of thing except you store the state in a comment that was made on top of the SWF.

Communicating with Acrobat and the PDF Document

Acrobat’s scripting language is JavaScript. In order to trigger events in an embedded RMA, you’ll need to call the exposed ActionScript functions inside it. If you know how to communicate between an HTML page in a browser and the Flash browser plug-in, this will feel pretty familiar.

To call Acrobat methods from the SWF, you’d use ExternalInterface.call just like you would with HTML. You can call any Acrobat method in the Acrobat JavaScript SDK. You can also call any methods that are in application level or document level JavaScripts and you can also use "eval" to send JavaScript into Acrobat from ActionScript and the return value of that method in Acrobat will be returned to your ActionScript method.

For a complete discussion of these advanced functions, please see my 5 part series called "Working with Rich Media Annotations".The series starts with the basics moves into more advanced topics and includes examples and source code for Flex but the ActionScript code is identical to what you’d need to do in Flash Professional.