FAQ

Installation & Operation

Performance

Analytics

Privacy & Disclosure

Advertising & Other Business

Getting In Touch

Miscellaneous

 

 

Installation and Operation

How do I integrate Pinch Analytics?

To integrate our Pinch Analytics library, please consult our documentation.  If you have any questions along the way, you can try searching or asking on our forum, or just contact us by e-mailing support@pinchmedia.com.

I've just integrated Pinch Analytics. When will my data appear?

Soon! At the moment, all of our reports except for 'statistics by region' and 'statistics by action' are set to aggregate multiple times per day. The aggregation cycle is not set to a specific schedule but instead a rolling cycle which will kick off a new aggregation on a server once the previous one has finished. Once a day, the 'statistics by region' and 'statistics by action' reports get aggregated while the other reports are paused. All of these cycles are subject to change as we tweak them in the future.

If it's been several hours, you still haven't seen anything, and we don't have any notices posted on the developer forums, it may be an implementation issue. Contact us at support@pinchmedia.com - we'd be happy to help troubleshoot.

What does the last aggregation date actually mean?

We have a number of servers which are responsible for processing and importing their own separate queue of incoming beacons. Each server is also responsible for aggregating its own unique set of reports. The final reports available on the developer site are a combination of all the separate reports from all these servers.

We display two timestamps related to the aggregation process on each report page: the most recent time all of the servers completed an aggregation, and the most recent time any of the servers completed an aggregation.  Data before the first timestamp is 100% aggregated, while between these two times - which represent our slowest server and our fastest server - is only partially available.

What data does Pinch Analytics collect from the phone?

For each application run, Pinch Analytics collects the following information:

  • the application version
  • the device model (iPhone, iPhone 3G, iPod Touch, etc.) and OS version
  • the device's unique identifier
  • the time the application started and stopped
  • any data you pass us as a custom action
  • the results of a simple piracy check
  • if CoreLocation is enabled (useCoreLocation:YES), the user's latitude and longitude
  • if Facebook Connect for iPhone is enabled, the user's age and gender

We also receive the standard information included with a regular HTTP request, like the user's IP.

When is the data sent to the server?

If a network connection is available, Pinch Analytics will send the data when you call [Beacon endBeacon] -- which we suggest doing as part of the  applicationWillTerminate: call.  If data is present on the phone, we also attempt to send it during initialization, when [Beacon initAndStartWithApplicationCode: useCoreLocation: useOnlyWifi] is called.  This is necessary to retrieve all application data -  since sometimes, when the network connection is spotty, the iPhone will kill applications before the data has been received.  Unsent data always remains in a local cache until successfully sent, when we delete it from the local device.

Should I enable Core Location in the Pinch Analytics library?

We don't recommend that developers enable Beacon's Core Location functionality — unless the application is already using Core Location for application-specific features. This is a user experience and trust issue; for example, it'd be strange for a crossword application to request a user's location unless it somehow made use of the location data in the app itself (local crossword competition, anybody?).

Furthermore, we recommend that developers skip the Core Location initialization in initAndStartBeaconWithApplicationCode:useCoreLocation:useOnlyWiFi: (as in, pass "NO" to useCoreLocation:), and instead pass a CLLocation object to Beacon once the application has requested a user's location. For instructions on how to do this please, refer to the documentation.

How do I prevent simulator data from showing up in my analytics?

You can add the simulator's UDID as an ignored device on your application preferences page. Unfortunately, there's no convenient way to retrieving the UDID from the simulator without going through code. You may use the following code snippet to retrieve the UDID:

NSLog(@"device id: %@", [UIDevice currentDevice].uniqueIdentifier);

What characters can I use in my action names?

You may use any 32 characters you please.

Is there a limit on the number of unique actions I can send in?

While the system will be able to handle upward to 5,000 unique actions, we recommend to developers to limit the number of unique actions to a small number of distinguished unique actions. The reason for this is because developer site is not optimized to compare many number of unique actions together. Every action we receive is treated as the same and once there's a large number of unique actions added, the developer site becomes more difficult to retrieve data out of.

I never got my confirmation e-mail. What should I do?

Our apologies - sometimes that happens.  In this case, contact us at support@pinchmedia.com with your username you used to sign up and we can hook you up.

What is product ID on the application creation/update page?

For iPhone developers, you can get your application's product ID by going to the page in iTunes where your application is sold, placing your mouse over the application name, and right-clicking. Select the 'Copy iTunes Store URL' button and paste the URL into a text editor. Your application's product ID is the number immediately after the 'id' parameter in the URL.

Why do you recommend that I call [Beacon endBeacon] last in applicationWillTerminate?

If your application has something to do at applicationWillTerminate, like saving a game's state or writing to a log, that code is crucial to the central functionality of your app and should take precedence over sending analytics data. Wouldn't you be miffed if you finally got a high score but it never got recorded? See the next question for details on how the watchdog timer can kill apps that take too long in applicationWillTerminate.

Why am I getting crash reports that say "failed to terminate" and mention Beacon?

The iPhone OS has a watchdog timer that keeps an eye on how long an application takes to terminate successfully. If an app takes too long (and "how long" is a mystery quantity known only to Apple), the OS assumes that it is hung, and kills the process.

In endBeacon, we instantiate a synchronous, main-thread-blocking network connection to transmit your analytics data to our servers. Fairly often, a user will be on a shaky network connection (running in and out of EDGE / 3G / wifi signal range), or the internet will decide to drop packets, or for *whatever* reason, the network connection stalls. At that point, we're still blocking the app from terminating properly because we're waiting for a successful response from our servers, and after the mystery timeout, the OS kills the app.

We set a network timeout interval of 5 seconds, which we found to be the sweet spot for networking in applicationWillTerminate — long enough to navigate a shaky network connection, but not too long that you get spammed by "failed to terminate" crash reports. If your app also does cleanup in applicationWillTerminate (see the previous question), the time can add up and app will be killed.

We consider "failed to terminate" crash reports (with stack traces that lead back to [Beacon endBeacon]) to be annoying, but "normal" behavior — sometimes the phone really does have to kill the app because of a stalled network.

Why am I getting errors about libsqlite when building under iPhone SDK 3.0?

In older releases of the iPhone SDK, there were numerous symbolic links ("aliases" in Mac parlance) to libsqlite.dylib (like "libsqlite3.0.8.6.dylib"). In 3.0, most of these have been removed. Many developers had their apps link against libsqlite3.0.8.6.dylib because it came up first in the list -- our stuff was compiled that way too.

To fix this, Get Info on your Target (you'll find this in the Groups & Files pane on the left side of the Xcode project window) and choose the General tab. Then, remove "libsqlite3.0.8.6.dylib" from the list of Linked Libraries and click the plus sign button to add "libsqlite3.dylib." (If Xcode ignores your wishes and instead adds "libsqlite3.0.8.6.dylib" again, even though you picked "libsqlite3.dylib," you'll need to find the "libsqlite3.0.8.6.dylib" item in the Groups & Files pane (perhaps under Frameworks, although Xcode can be rather sloppy and it could be anywhere), delete it, and then follow the above steps again.)

 

 

Performance

Does using Pinch Analytics impact my application performance?

Generally, no - although using Pinch Analytics, like any library, will result in a minor increase in your binary size and a small increase to the memory footprint.

How much space does your analytics library require?

Pinch Analytics adds around 52 kb to your application's binary size.

How much memory does your analytics library use?

The library uses about 110kb of memory on the phone, most of which is related to using sqlite3 and the phone's networking facilities. Apps already making use of sqlite3 or networking will see less of an increase in memory usage.

How much bandwidth does your analytics library use?

Not much. A single beacon representing a session is about a third of a kilobyte, and sub-beacons are about a tenth. The vast majority of applications will transmit fewer than 10 kilobytes per session.

 

 

Analytics

What do your metrics mean?

Please consult our metric glossary for a break down on how each metric is computed and what it means.

Why do my unique users per day not add up to my unique users for the week?

This is due to recurring users. One user might use the application multiple times over the course of the week, which would show up as one unique user for each day in our reporting.  However, that user would only be counted once for the unique users for the week.

Why am I seeing new users for my application which is no longer available for purchase?

This is likely caused by people who have upgraded or exchanged physical devices. Our new user and unique user metrics are based on the device's unique identifier, so if an existing user installs an application to another device using the same iTunes account, they will be shown as two unique users. Unfortunately, we have no way of knowing which iTunes account an application installation is tied to.

Why are my Pinch Analytics stats different from Apple's download numbers?

Our numbers can be different from Apple's for a number of reasons.  First, make sure you're looking at comparable things - Apple's downloads are similar to (but not exactly the same as) our new user metric.  For more details on the metrics, see our metric glossary.

New users metric vs Apple's reported downloads

These numbers should be quite similar, but may be off slightly when comparing day to day, for a variety of reasons.

First, Apple reports downloads on the date that an application was purchased from iTunes.  We report new users the first time a device runs the application. These two times often but don't always occur on the same calendar day.

Next, our calendar day uses Eastern Standard Time (UTC-5:00).  Apple's reporting varies by region.

Next, our data arrives over time.  If a device doesn't have a network connection when an application shuts down, Pinch Analytics can't get the data.  Instead, it's cached on the device until the application is run again.  We'll receive the older data from the device eventually and then attribute it to the proper date -- but this means our numbers change slightly over time, and dates closest to the present may slightly undercount.

When the new users metric is dramatically higher then Apple's download numbers

This usually happens at least once for paid applications - it's a strong indicator of application piracy.  Apple will only report on legitimate installs, while we report on all usage, from paying customers and pirates alike.

When piracy first occurs, the typical paid application gets five times as much usage from pirated installs then legitimate installs, although we've seen much higher ratios on occasion.  Happily, the magnitude of piracy rapidly declines, with new pirated installs decreasing rapidly after the application is first cracked and distributed.

When your application is new to Pinch Media, but not to the AppStore

Many application developers find out about Pinch Media after the initial launch of their applications and add Pinch Analytics as part of an update.  When this happens, new user numbers will be artificially high for a couple weeks, since we can't distinguish users who are using your application for the very first time from users who have been using your application for ages but just upgraded.  They may not be new to you, but they're new to Pinch Analytics!

After a couple of weeks, this effect becomes quite minor.

My application's new users jumped rapidly, but this isn't reflected in Apple's download numbers. What's up?

Likely, piracy - this is exactly the type of behavior we see when an application's cracked and distributed.  See the "Why are my Pinch Analytics numbers different from Apple's download numbers?" question for more information.

What does 'unknown' mean in the statistics by region report?

That depends on the level of resolution.  At the country level, we use an IP-based lookup to quickly provide country-level data for everyone.  If you see 'unknown' here, it means that IP address wasn't in our database.  At the region (state, in America) or city level, which is only accessible if the application's sending in latitude & longitude points, 'unknown' means the user declined to share their location with the application.  If your 'unknown' bucket is large, it means you're not offering a compelling reason for the users to share their applications.  (Our analytics generally are not a compelling reason on their own -- we recommend that developers ony collect latitude and longitude points when their applications use it for other functionality.)

How do I get my data out of your system?

You can view all of your aggregated reports on the developer site, and export all your aggregated data in CSV format.  You can also make use of our full API to export and integrate your statistics with other applications.

What time zone are your stats based on?

All of our reports are based on Eastern Standard Time (UTC-5:00).

How often are your reports updated?

That depends on the report.  Most reports get several updates through out the day however the statistics by action and the statistics by region reports only get updated once a day since they are more computationally expensive to aggregate.

How do cracked applications affect my sales summaries?

They don't! Since Pinch Analytics tracks whether beacons are coming from cracked applications, we are able to subtract those numbers from the totals to give you more accurate sales statistics. In the past, we'd occasionally get angry emails from users who observed that our sales numbers were much bigger than Apple's, and this was always an indicator that the developer's application had been cracked. We're happy to no longer have to be the bearer of bad news!

How do you detect whether a device is jailbroken or an application is cracked?

It's nothing special - we use the same methods you'll find with a quick search. Of course, these methods are not perfect; it's reasonable to expect some false positives and negatives.

 

 

Privacy & Disclosure

Do I need to mention Pinch Analytics in my terms of service?

The short answer - 'no'.  There's a default terms of service provided by Apple that the users of all iPhone applications agree to, and this covers data transmission and storage.  That said, some developers do disclose that they're collecting anonymous, non-personally-identifying usage data.  It's up to you.

What does Pinch Media do with my data once it's collected?

When data comes in the door, we take it and aggregate it into a variety of reports.  These reports are then made availabe to you through a web interface, our CSV exports, and our full API.  We also run some system-wide reporting - using your data, along with other applications', to produce reports by price point, by application category, by operating system, and a variety of other dimensions. The raw data itself is backed up and securely stored so the aggregated tables can be recreated in case of emergency.

Our system-wide reporting is never made public unless it's completely impossible to determine which applications' data were used to create it - for example, we might release a report based off of fifty applications, but not one based off of three.  We never share an individual application's data with anyone without the application owner's explicit permission.

Can you tell me about my competitors?

Absolutely not.  You wouldn't want us to tell your competitors about your application, would you?

We have a rule around the office - we don't publicly discuss who's using Pinch Media without their explicit permission, and we never share or display publicly data that could individually identify an application.  Your choice of analytics provider is your business.

What can't I collect in subbeacons?

Don't send us any personally-identifiable data - we don't want it, and we won't keep it.  If we do see you sending in anything that can individually track or identify a specific user, we'll turn off the subbeacon feature for your application.  Personally-identifiable data includes (but isn't limited to) phone numbers, addresses, credit card numbers, full names, and e-mail addresses - if you're unsure about something, just ask us.

Can I track individual users?

No, absolutely not. We will never report on an individual user's usage.

 

 

Advertising & Other Business

What does your product cost?

The basic version of Pinch Analytics is completely free, and we're going to keep it that way.  We'll definitely charge for certain premium features in the future.

Can you write my iPhone application for me?

Sorry - we can't do it. We're trying to get a lot done over here and don't have time to develop iPhone applications for others.

Do you offer advertising?

Sort of.  There's no ad sales team at Pinch Media, and we don't work directly with advertisers.  However, we've partnered with JumpTap, a mobile ad network focused on premium advertisers.  We provide the technology, JumpTap provides the advertising, application developers provide the spots to run ads.  We target application developers who would benefit from JumpTap's worldwide sales force and premium advertising relationships. Once we are engaged with a developer, our Pinch Advertising library is optimized with your users in mind - we keep bandwidth and memory use at an absolute minimum, and only offer ad units designed to complement your user experience, instead of competing with it.

An important caveat: we believe strongly that developers should only use Pinch Advertising in ways that do not detract from the user experience, and only when it makes economic sense - sometimes advertising performs better than paid downloads, but often it does not.  If you'd like to discuss whether your application is suitable for advertising, from JumpTap or from any other party, just get in touch.

How much traffic does my application have to get to use advertising?

JumpTap's not a self-serve solution - instead, they sell ad space directly to brand advertisers.  Because of this, they typically work with apps generating at least 500,000 impressions per month. Of course, numerous factors go into the decision to work with any one developer, including application type, application content, and audience demograpics.

Why am I only seeing Pinch Media ads?

We usually get this question from people implementing our ad library through a third party library. Advertising through Pinch Media isn't self-serve - we recommend your application to our partner, JumpTap, and they make a decision on an app-by-app basis. You can enroll to the advertising program through the developer site and enter the queue for acceptance. Just a note however that the process takes a couple of weeks due to a backlog since JumpTap evalutates each application separately.

If admitted to our advertising program, you wouldn't be managing advertisements, you'd be displaying whatever the ad network managed to sell. Most ad providers work the same way.

We do encourage anyone looking to implement advertising in their application, no matter what advertising program you went with, to try out our analytics service. This is essentially important when dealing with an ad network such as JumpTap since usage information is key in making the decision to accept an application to an advertising program.

 

 

Getting In Touch

How do I get in touch with you?

Please feel free to send email to support@pinchmedia.com or use our feedback form.

I've got a press inquiry. Who should I talk to?

Just send an email to bizdev@pinchmedia.com or use our feedback form, and someone will get in touch shortly.

I have a suggestion. Where do I send it?

First of all, thanks!  Much of our product roadmap is based on user suggestions.  You can email the team at suggestion@pinchmedia.com or use our feedback form to get in touch.

 

 

Miscellaneous

What is the world's most majestic animal?

Although certain people around the office think it resembles a giant rat, it's been scientifically proven that the capybara is the most majestic animal on earth.