Share 1.0.11

A GameMaker: Studio extension developed by Beneton Software

Table of Contents

Requirements

This extension was fully tested on GameMaker: Studio v1.4.1772, compiling for the following targets: iOS, iOS (YYC), Android / Fire, and Android / Fire (YYC). It was also successfully tested with GameMaker Studio 2 for Windows (v2.0.7.171), although it is not officially supported at the moment.

iOS

Android

Getting Started

This extension package contains an example, in the form of GameMaker: Studio resources (sprites, objects, rooms, etc.) that can be imported in your project. This example is completely optional; it is meant to showcase what can be achieved with the extension, as well as help get familiarized with its functionality and quickly dive into the code. It is not meant to be used “as is”, and it doesn’t replace this documentation. If you wish to check out the example, we recommend adding the extension to an empty project, importing all the resources, moving the room that fits your device (phone or tablet) to the first position, and running it on your iOS or Android device (note: for Android, you have to create a full APK).

There are two ways to share things with the Share extension: the simple functions (just one line of code to share some text, a URL, an image, or a file) as well as the more elaborate and more powerful advanced functions, which are prefixed by share_ext_. So it can be as simple as:

share_image("screenshot.png");

or as customized as:

share_ext_prepare();
share_ext_add_image("screenshot.png");
share_ext_add_text("I just scored " + str(score) + "!");
share_ext_add_url("http://your-game-url.com");
share_ext_set_activity(ACTIVITY_TYPE_TWITTER);
share_ext_launch();

Please note that in both cases, the file screenshot.png must exist in the save area to be shared properly (please read the “File System Limits” section of the GameMaker: Studio manual if you don’t know what that is).

In other words, the share_ext_* functions give you more control such as the ability to share more than one item at once and set an activity to share with, as opposed to letting the user choose (see the “Constants” section of this document for a list of all supported activities).

Below is the complete list of functions. If you are experiencing any issue, please make sure to check out the “Troubleshooting” section at the bottom of this document. If you don’t find an answer to your question, don’t hesitate to contact us through the YoYo Games Marketplace (link at the top). Thank you!

Functions

share_text(text)

Opens the activity chooser to share a string as plain text.

String text The text to share.

share_text_ext(text, subject, email)

Opens the activity chooser to share a string as plain text, accepting extra information that is used if the user chooses to share by email (or any app that supports “subject” and/or “email” parameters).

String text The text to share.

String subject The subject of the email/message.

String email The email address to put by default in the “To” field (this argument only takes effect on Android; use share_ext_add_recipient() if you want that functionality on iOS).

share_url(url)

Opens the activity chooser to share a URL. This function gives different share options than share_text() on iOS, but on Android it does exactly the same thing.

String url The URL to share.

share_image(filename)

Opens the activity chooser to share an image. Note: The file must be located in the “save area” of your game, so if it part of your bundle (i.e. in your “Included Files”), you must copy it to the save area first. Read the “File System Limits” section of the GameMaker: Studio manual for more information.

String filename The filename of the image to share (without the path).

share_file(filename)

Opens the activity chooser to share a file (any format). Read the note in share_image().

String filename The filename of the file to share (without the path).

share_set_popover_origin(x, y)

iOS only

Sets the origin of the share popover to a single point on the screen. The popover only appears on iPad as it takes the form of a panel sliding from the bottom of the screen on iPhone/iPod Touch. Note: The positions are in points, not pixels. To convert between the two units, you can use the iOS Points extension.

Real x

Real y

share_set_popover_region(x, y, width, height)

iOS only

Sets the origin of the share popover to a rectangle on the screen. If you use this function, it overrides share_set_popover_origin() (and vice versa). This one is more powerful because you can define a rectangle to be a region of interest that you are certain the popover will not appear over.

Real x

Real y

Real width

Real height

share_set_dialog_title(title)

Android only

Changes the title of the share dialog. The default title is "Share using".

String title The new title of the share dialog.

share_did_finish()

Returns whether the share process ended since the last call to this function. It does not necessarily mean that it ended successfully; for that you need to call share_get_completed().

Returns: Boolean

share_get_completed()

Returns whether the user completed the last share operation without cancelling. It does not necessarily mean the share was successful at the server level (unfortunately there is no way to detect that with the activity view). Note: On Android, this function often returns false even when the operation was successful. This is because Android’s startActivityForResult() "should only be used with Intent protocols that are defined to return a result", and unfortunately the protocol used for sharing (ACTION_SEND) is not. Some activities still return a result, but overall this function is not reliable.

Returns: Boolean

share_get_chosen_activity()

iOS only

Returns the activity type the user chose for the last share operation.

Returns: Real The chosen activity type; one of the ACTIVITY_TYPE_* constants.

share_get_chosen_activity_string()

iOS only

When share_get_chosen_activity() returns ACTIVITY_TYPE_OTHER, this function can be used to get more information on the app selected by the user.

Returns: String A unique identifier for the chosen activity (example: "com.evernote.iPhone.Evernote.EvernoteShare").

share_ext_prepare()

Prepares a more advanced share operation. This function must be called before any of the other share_ext_* functions. With these functions you can share a piece of text with multiple images, for instance. You can also force an activity such as Facebook or Twitter instead of letting the user choose, with share_ext_set_activity(). After you have set all the parameters you want, you can launch the share operation you prepared with share_ext_launch().

share_ext_add_text(text)

Adds a string of plain text to the current share operation.

String text The text to share.

share_ext_add_url(url)

Adds a URL to the current share operation.

String url The URL to share.

share_ext_add_image(filename)

Adds an image to the current share operation. Read the note in share_image().

String filename The filename of the image to share (without the path).

share_ext_add_file(filename)

Adds a file (any format) to the current share operation. Read the note in share_image().

String filename The filename of the file to share (without the path).

share_ext_set_activity(activity_type)

Sets the activity to use for the current share operation. Only the following activity types are supported by this function: ACTIVITY_TYPE_FACEBOOK, ACTIVITY_TYPE_TWITTER, ACTIVITY_TYPE_WEIBO (iOS only), ACTIVITY_TYPE_MESSAGE, and ACTIVITY_TYPE_MAIL. When you use this function, share_ext_launch() skips the activity chooser and goes straight to the given activity (if available), except for ACTIVITY_TYPE_MESSAGE and ACTIVITY_TYPE_MAIL on Android where the chooser still appears. Note: When setting the activity to ACTIVITY_TYPE_MESSAGE on Android, you can only share text and URLs (no images or files).

Real activity_type The activity type to use; one of the ACTIVITY_TYPE_* constants.

share_ext_exclude_activity(activity_type)

iOS only

Excludes an activity from the activity chooser for the current share operation. You can exclude multiple activities for the same share operation; just call this function multiple times.

Real activity_type The activity type to exclude; one of the ACTIVITY_TYPE_* constants.

share_ext_set_subject(subject)

Sets the subject of the email/message for the current share operation. Only a few activities consider this value.

String subject The subject of the email/message.

share_ext_add_recipient(email_address)

Adds a recipient to the email/message for the current share operation. On iOS, only ACTIVITY_TYPE_MESSAGE and ACTIVITY_TYPE_MAIL consider this value, and on Android, only a few applications do.

String email_address The recipient’s email address.

share_ext_set_body_is_html(true_or_false)

Sets whether the body text of the current share operation (set by share_ext_add_text()) should be treated as HTML. The default is false.

Boolean true_or_false Set to true for HTML, or false for plain text.

share_ext_set_intent_action(intent_action)

Android only

Sets the action to use in the underlying Intent object on Android. The default is INTENT_ACTION_SEND. If set to INTENT_ACTION_VIEW, whatever application you or the user chooses will simply open the selected image or file, rather than guiding the user to share it.

Real intent_action The intent action to use; one of the INTENT_ACTION_* constants.

share_ext_launch()

Launches the current share operation with all the parameters that were set since the last call to share_ext_prepare(). The function returns false when it fails to show anything to the user. That can happen when the activity is set to ACTIVITY_TYPE_FACEBOOK or ACTIVITY_TYPE_TWITTER and the user does not have the required application installed on his device, or on iOS when the activity is set to ACTIVITY_TYPE_MAIL and there is no email account listed on the device.

Returns: Boolean Whether the share operation was successfully initiated.

Constants

Activity Types

Intent Actions

Troubleshooting

The functions don’t seem to do anything on Android.

This is most likely because you are using the command “Run the game” (or “Run in debug mode”) instead of “Create Executable for Target”. GameMaker: Studio requires to create a full APK for extensions to work (this is not the case on iOS).

Sharing text on Facebook doesn’t work.

Unfortunately, that is not a bug, it is “by design”. Facebook doesn’t want you to “pre-fill the user message parameter with any content the user didn’t enter themselves”. On iOS, however, there is a workaround that consists of entering a hashtag, so as long as the string you pass to share_text() or share_ext_add_text() starts with the # character and doesn’t contain any spaces, it will be added to the post. Unfortunately this does’t seem to work on Android at the moment. Of course, you can still share URLs and images (although not together because there’s a limit of one “attachment” per Facebook post).

I want to share a screenshot of my game but the screenshot is black or missing.

Please refer to the included example “Take screenshot and share on Facebook”. You should save the application_surface with surface_save() and share the resulting PNG image.

I want to share multiple images at once using the share_ext_* functions, but Twitter (or some other app) doesn’t show up in the options.

Unfortunately, some apps do not support multiple images in one share operation, including Twitter on both iOS and Android (even though the Twitter website itself supports multiple attachments). You can either launch a different share operation for each image, or merge your images into one using a surface.

Changelog

1.0.11 (2018-01-05)

1.0.10 (2017-11-05)

1.0.9 (2017-08-06)

1.0.8 (2017-01-11)

1.0.7 (2016-12-16)

1.0.6 (2016-11-03)

1.0.5 (2016-10-31)

1.0.4 (2016-10-30)

1.0.3 (2015-10-25)

1.0.2 (2015-02-19)

1.0.1 (2015-02-14)

1.0.0 (2015-01-29)